### Manual Installation and Setup

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Clone the repository and install DroidMind from source using the uv package manager. Includes steps for setting up virtual environments and installing dependencies.

```bash
# Clone the repository
git clone https://github.com/hyperb1iss/droidmind.git
cd droidmind

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On macOS/Linux

# Install dependencies
uv sync --no-dev  # For running
uv sync --all-groups  # For development

# Run DroidMind
droidmind --transport stdio  # For IDE integration
droidmind --transport sse    # For web UIs (http://localhost:4256)
```

--------------------------------

### System Tombstone Example

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

This is an example of a system tombstone log, which captures information about native crashes.

```text
*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
Build fingerprint: 'google/sdk_gphone64_x86_64/generic_x86_64:12/SE1A.220601.001/8804948:userdebug/dev-keys'
Revision: '0'
ABI: 'x86_64'
pid: 9012, tid: 9034, name: Thread-2  >>> com.example.crasher <<<
```

--------------------------------

### Install Application

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Installs an APK file onto the Android device. Permissions can be granted automatically during installation.

```python
await app_operations(
    serial="emulator-5554",
    action="install_app",
    ctx=context,
    apk_path="/home/user/myapp.apk",
    reinstall=True,
    grant_permissions=True
)
```

--------------------------------

### Start Application

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/app_management.md

Launch an application on the device. Specify the `package` name and optionally an `activity` to start a specific component. If `activity` is omitted, the default main activity is launched.

```python
droidmind.start_app(device_serial='emulator-5554', package='com.example.myapp', activity='.ui.SettingsActivity')
```

--------------------------------

### Install DroidMind Dependencies

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/installation.md

Install DroidMind and its dependencies using uv. Use '--no-dev' for running, and '--all-groups' for development.

```bash
uv sync --no-dev
```

```bash
uv sync --all-groups
```

--------------------------------

### Start Activity with Intent

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Starts a specific activity within an application using an intent, with support for custom extras.

```python
await app_operations(
    serial="emulator-5554",
    action="start_intent",
    ctx=context,
    package="com.example.myapp",
    activity=".DeepLinkActivity",
    extras={"url": "myapp://home", "source": "droidmind"}
)
```

--------------------------------

### Get App Information

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieves detailed information about an application, including its version, installation path, size, and running status.

```python
await app_operations(
    serial="emulator-5554",
    action="get_app_info",
    ctx=context,
    package="com.example.myapp"
)
```

--------------------------------

### Install DroidMind with uvx

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Configure DroidMind for IDE integration using uvx for a zero-install setup. This JSON defines the MCP server configuration.

```json
{
  "mcpServers": {
    "droidmind": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hyperb1iss/droidmind",
        "droidmind",
        "--transport",
        "stdio"
      ]
    }
  }
}
```

--------------------------------

### Start Application

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Launches an application on the Android device. A specific activity can be targeted for launch.

```python
await app_operations(
    serial="emulator-5554",
    action="start_app",
    ctx=context,
    package="com.example.myapp",
    activity=".MainActivity"
)
```

--------------------------------

### Example AI Response: Read Small Text File

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/file_system.md

Example of an AI response displaying the content of a small text file read from the device.

```text
# File Contents: /sdcard/Download/MySubFolder/config.txt

```text
# Configuration File
ENABLE_FEATURE_X=true
API_ENDPOINT=https://api.example.com
DEBUG_MODE=false
```

The file `config.txt` contains these configuration settings.

```

--------------------------------

### Install Application from APK

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/app_management.md

Install an application using its APK file path. The `apk_path` must be local to the DroidMind server. Use `reinstall=True` to allow reinstallation and `grant_permissions=True` to grant all declared permissions.

```python
droidmind.install_app(device_serial='emulator-5554', apk_path='/Users/bliss/Downloads/new_app.apk', reinstall=False, grant_permissions=True)
```

--------------------------------

### Start Application

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/example_queries.md

Launch a specified application on the Android device. This is often the first step in UI automation or interaction sequences.

```text
start_app com.android.settings emulator-5554
```

--------------------------------

### Example AI Response: File Written Successfully

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/file_system.md

Confirmation message from the AI after successfully writing content to a file on the device.

```text
# ✨ File Written Successfully

- **Path**: /sdcard/hello.txt
- **Size**: 16 bytes
- **Device**: emulator-5554

The content has been saved to the file.

```

--------------------------------

### ANR Trace Example

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

This is an example of an ANR trace log. It shows the state of threads, including the main thread being blocked while waiting for a lock.

```text
# Application Not Responding (ANR) Traces
## ANR Trace #1: anr_2023-01-15-10-35-00-123.txt
**File Info:** -rw-rw---- 1 system system 123456 2023-01-15 10:35 /data/anr/anr_2023-01-15-10-35-00-123.txt
----- pid 8765 at 2023-01-15 10:35:00 -----
Cmd line: com.example.myapp
DALVIK THREADS (15):
"main" prio=5 tid=1 Blocked
  | group="main" sCount=1 dsCount=0 flags=1 obj=0x12c08a00 self=0xb4800200
  | sysTid=8765 nice=0 cgrp=top-app sched=0/0 handle=0xb73ff4f4
  | state=S schedstat=( 0 0 0 ) utm=93 stm=42 core=0 HZ=100
  | stack=0xbe227000-0xbe229000 stackSize=8MB
  | held mutexes= "mutator lock"(shared held)
  at com.example.myapp.HeavyComputation.perform(HeavyComputation.java:25)
  - waiting to lock <0x09a8f2c8> (a java.lang.Object) held by thread tid=10
...
```

--------------------------------

### Example AI Response: File Uploaded Successfully

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/file_system.md

Confirmation message from the AI after successfully uploading a file to the device.

```text
# ✅ File Uploaded Successfully

The file `my_app.apk` (12.5 MB) has been uploaded to `/sdcard/Download/` on device emulator-5554.

**Details**: 1 file pushed. 2.5 MB/s (12533120 bytes in 4.780s)

```

--------------------------------

### Logcat Crash Report Example

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

This example shows a Java crash report as seen in logcat, including the exception type and stack trace.

```text
01-15 10:40:15.123  9012  9034 E AndroidRuntime: FATAL EXCEPTION: Thread-2
01-15 10:40:15.123  9012  9034 E AndroidRuntime: Process: com.example.crasher, PID: 9012
01-15 10:40:15.123  9012  9034 E AndroidRuntime: java.lang.NullPointerException: Attempt to invoke virtual method 'java.lang.String java.lang.Object.toString()' on a null object reference
...
```

--------------------------------

### List Installed Packages

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieves a list of installed packages on the Android device. System apps can be included, and the output can be filtered by name and count.

```python
await app_operations(
    serial="emulator-5554",
    action="list_packages",
    ctx=context,
    include_system_apps=False,
    include_app_name=True,
    max_packages=100
)
```

--------------------------------

### Example AI Response: File Too Large

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/file_system.md

This is an example of an AI response when a requested file exceeds the maximum size limit for reading directly. It suggests using `pull_file`.

```text
# ⚠️ File Too Large

The file `/sdcard/Download/large_log.zip` is 5.7 MB, which exceeds the maximum size limit of 100.0 KB.

Use `pull_file` to download this file to your local machine instead.

```

--------------------------------

### Run DroidMind with Custom Arguments

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/docker.md

Examples of running the DroidMind container with specific transport and configuration flags.

```bash
docker run -d -p 4256:4256 \
  -e DROIDMIND_TRANSPORT=sse \
  -e ADB_SERVER_SOCKET=tcp:host.docker.internal:5037 \
  --name droidmind-custom-sse \
  droidmind:latest droidmind --adb-path /custom/adb --debug
```

```bash
docker run -d -p 8000:8000 \
  --name droidmind-explicit-sse \
  droidmind:latest droidmind --transport sse --host 0.0.0.0 --port 8000 --log-level DEBUG
```

--------------------------------

### List Installed Packages

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/app_management.md

Use the `list_packages` tool to discover applications on a device. Set `include_system_apps` to `True` to see system applications.

```python
droidmind.list_packages(device_serial='emulator-5554', include_system_apps=False)
```

--------------------------------

### Example Command Output

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/shell_commands.md

Standard output format returned by DroidMind after executing a shell command.

```text
# Command Output from emulator-5554

-rw-rw---- 1 u0_a123 sdcard_rw 1024 2023-01-15 10:00 myfile.txt
drwxrwx--x 1 u0_a123 sdcard_rw 0 2023-01-14 09:00 Download
drwxrwx--x 1 u0_a123 sdcard_rw 0 2023-01-13 08:00 Pictures
... (output may be truncated if it exceeds max_lines or max_size)
```

--------------------------------

### Output Truncation Notice

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/shell_commands.md

Example of the footer appended to command output when limits are exceeded.

```text
[Output truncated: 100000 chars, 1500 lines]
[Command output truncated: 1500 lines, 97.7 KB]
```

--------------------------------

### Configure Claude Desktop for DroidMind with uvx

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/quickstart.md

This JSON configuration can be added to `claude_desktop_config.json` to allow Claude Desktop to automatically start DroidMind using `uvx` with stdio transport.

```json
{
  "mcpServers": {
    "droidmind": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hyperb1iss/droidmind",
        "droidmind",
        "--transport",
        "stdio" // Default and preferred for Claude Desktop
      ]
      // Add "workingDirectory": "/path/to/your/droidmind/project" if needed
      // Add "env": { ... } if DroidMind needs specific environment variables
    }
  }
}
```

--------------------------------

### Get App Manifest

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieves the application manifest, including version, SDK levels, permissions, and components.

```python
await app_operations(
    serial="emulator-5554",
    action="get_app_manifest",
    ctx=context,
    package="com.example.myapp"
)
```

--------------------------------

### Start Android Activity with Intent

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Launches an Android activity using an explicit intent. Requires 'package' and 'activity' names. Optional 'extras' can be provided.

```python
# Start activity with intent
# Requires: package, activity
# Optional: extras
await android_ui(
    ctx=context,
    serial="emulator-5554",
    action="start_intent",
    package="com.android.settings",
    activity=".Settings",
    extras=None
)
```

--------------------------------

### Get Device Properties

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/example_queries.md

Use `list_devices` and `device_properties` to get a quick overview of a connected Android device. Ensure the device is connected and recognized by DroidMind.

```text
list_devices
device_properties your_device_serial
```

--------------------------------

### Get System Properties

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieves a specific system property, such as the Android release version, using the 'getprop' command.

```python
await shell_command(
    serial="emulator-5554",
    command="getprop ro.build.version.release",
    ctx=context
)
```

--------------------------------

### Dumping Heap for Memory Analysis

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Instructions and examples for requesting heap dumps (Java and native) using DroidMind.

```APIDOC
## Dumping Heap for Memory Analysis

### Description
Heap dumps are snapshots of an app's memory, useful for diagnosing memory leaks and understanding object allocation. DroidMind can capture both Java and native heap dumps.

### How to Ask Your AI Assistant

#### Java Heap Dump
```
Dump the Java heap for the app `com.example.memoryhog` on `emulator-5554`.
```

#### Native Heap Dump
```
Capture a native heap dump for process ID `12345` on `your_device_serial` and save it to `/tmp/native_heap.hprof`.
```

### DroidMind Action: `dump_heap` Tool

This tool is used to capture heap dumps.

#### Parameters

- **`package_or_pid`** (string) - Required - The app package name or its Process ID (PID).
- **`output_path`** (string) - Optional - Local path on the DroidMind server machine to save the heap dump file. If empty, a default temporary location is used.
- **`native`** (boolean) - Optional (default: `False`) - Whether to capture a native heap dump (C/C++) instead of a Java heap dump. Native dumps often require root.
- **`timeout_seconds`** (integer) - Optional (default: `120`) - How long to wait for the dump operation to complete.

### Example Response (Java Heap Dump)

```
Capturing Java heap dump for process com.example.memoryhog...
... Java heap dump saved to: /tmp/droidmind_heapdump_XXXXXX/com.example.memoryhog_java_heap_20230115_110530.hprof (5.75 MB)
```

### Analyzing Heap Dumps

After obtaining a heap dump file (typically `.hprof`), you can analyze it using:

1.  **Conversion (for Java dumps):**
    ```bash
    hprof-conv /path/to/your/dump.hprof converted.hprof
    ```
2.  **Tools:**
    *   Android Studio's Memory Profiler.
    *   Eclipse Memory Analyzer (MAT).
```

--------------------------------

### Get App Activities

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieves a list of activities and their associated intent filters for a specified application package.

```python
await app_operations(
    serial="emulator-5554",
    action="get_app_activities",
    ctx=context,
    package="com.example.myapp"
)
```

--------------------------------

### Get App Permissions

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieves information about declared, requested, and runtime permissions for a given application package.

```python
await app_operations(
    serial="emulator-5554",
    action="get_app_permissions",
    ctx=context,
    package="com.example.myapp"
)
```

--------------------------------

### Battery Statistics Example

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

This snippet displays the current battery status of an Android device, including power source, charge level, voltage, and temperature.

```text
Current Battery Service state:
  AC powered: false
  USB powered: true
  Wireless powered: false
  Max charging current: 0
  Max charging voltage: 0
  Charge counter: 0
  status: 2
  health: 2
  present: true
  level: 75
  scale: 100
  voltage: 4200
  temperature: 250
  technology: Li-ion
```

--------------------------------

### Run DroidMind with SSE Transport (Recommended)

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/docker.md

Start DroidMind in detached mode using SSE transport, mapping port 4256 for external connections. This is the recommended method for integrating with AI assistants.

```bash
docker run -d -p 4256:4256 -e DROIDMIND_TRANSPORT=sse --name droidmind-server droidmind:latest
```

--------------------------------

### Bug Report Generation Confirmation (without output path)

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

This example shows the AI's response when a bug report is captured without a specified output path, indicating a temporary file location.

```text
Okay, I'm capturing the bug report...
...
# Bug Report for emulator-5554
Temporary file saved to: `/tmp/droidmind_bugreport_XXXXXX/bugreport_emulator-5554.zip` (15.23 MB)
```

--------------------------------

### Clone DroidMind Repository

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/installation.md

Use this command to clone the DroidMind repository from GitHub. Ensure you have Git installed.

```bash
git clone https://github.com/hyperb1iss/droidmind.git
cd droidmind
```

--------------------------------

### Get File Statistics

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieves statistics for a specified file or directory, including type, size, owner, permissions, and modification date.

```python
await file_operations(
    serial="emulator-5554",
    action="file_stats",
    ctx=context,
    path="/sdcard/Download"
)
```

--------------------------------

### Perform Swipe Action on Android Device

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Simulates a swipe gesture on the Android device. Specify start and end coordinates, and optionally duration.

```python
await android_ui(
    ctx=context,
    serial="emulator-5554",
    action="swipe",
    start_x=500,
    start_y=1500,
    end_x=500,
    end_y=500,
    duration_ms=500
)
```

--------------------------------

### Bug Report Generation Confirmation (with output path)

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

This is an example confirmation message when a bug report is captured and saved to a specified local path on the DroidMind server.

```text
Okay, I'm capturing the bug report from emulator-5554. This might take a few minutes...
...
Bug report saved to: /tmp/my_bug_report.zip (15.23 MB)
```

--------------------------------

### Get File/Directory Statistics on Android

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieve statistics for a file or directory on an Android device. Requires the path to the file or directory.

```python
# Get file/directory statistics
# Requires: path

```

--------------------------------

### Run DroidMind in SSE Mode

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/installation.md

Start DroidMind using the Server-Sent Events (SSE) transport, typically for web UIs or AI assistants. It defaults to http://localhost:4256.

```bash
droidmind --transport sse
```

--------------------------------

### Prepare Application for Testing

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/example_queries.md

Reset an application to a fresh state by stopping it, clearing its data and cache, and then restarting it. This is crucial for reliable testing of onboarding flows or initial states.

```text
stop_app com.example.testapp emulator-5554
clear_app_data com.example.testapp emulator-5554
start_app com.example.testapp emulator-5554
```

--------------------------------

### Manage Development Environment with uv

Source: https://github.com/hyperb1iss/droidmind/blob/main/README.md

Commands for dependency synchronization, testing, linting, and type checking within the development environment.

```bash
# Install/update dependencies (creates/updates `.venv`)
uv sync --all-groups

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Run type checking
uv run pyright
```

--------------------------------

### Create Virtual Environment with uv

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/installation.md

Create a Python virtual environment using uv. This isolates project dependencies.

```bash
uv venv
```

--------------------------------

### GET /device_battery_stats

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Retrieves current battery status and power consumption metrics from the device.

```APIDOC
## GET /device_battery_stats

### Description
Analyzes and returns the current battery state, health, and usage statistics.

### Method
GET

### Endpoint
/device_battery_stats

### Parameters
#### Query Parameters
- **device_serial** (string) - Required - The serial identifier of the target device.
```

--------------------------------

### GET /device_anr_logs

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Retrieves Application Not Responding (ANR) traces from a specified Android device.

```APIDOC
## GET /device_anr_logs

### Description
Retrieves the latest ANR logs from a specific device serial.

### Method
GET

### Endpoint
/device_anr_logs

### Parameters
#### Query Parameters
- **device_serial** (string) - Required - The serial identifier of the target device (e.g., emulator-5554).
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/installation.md

Activate the created virtual environment. The activation command differs based on your operating system and shell.

```bash
source .venv/bin/activate
```

```powershell
.venv\Scripts\Activate.ps1
```

```cmd
.venv\Scripts\activate.bat
```

--------------------------------

### Create Directory

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Creates a new directory at the specified path on the Android device.

```python
await file_operations(
    serial="emulator-5554",
    action="create_directory",
    ctx=context,
    path="/sdcard/MyApp/data"
)
```

--------------------------------

### GET /device_crash_logs

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Retrieves application crash logs, including system tombstones and Java crash reports.

```APIDOC
## GET /device_crash_logs

### Description
Fetches crash reports and system tombstones for the specified device.

### Method
GET

### Endpoint
/device_crash_logs

### Parameters
#### Query Parameters
- **device_serial** (string) - Required - The serial identifier of the target device.
```

--------------------------------

### Swipe Gesture

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Performs a swipe gesture on the Android device's screen between specified start and end coordinates.

```python
# Swipe gesture
# Requires: start_x, start_y, end_x, end_y
await android_ui(
    ctx=context,
    serial="emulator-5554",
    action="swipe",
    start_x=100,
    start_y=100,
    end_x=500,
    end_y=500
)
```

--------------------------------

### Configure IDE for DroidMind with uvx

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/quickstart.md

Use this JSON configuration in your IDE's MCP settings file (e.g., `.cursor/mcp.json`) to enable `uvx` to fetch and run DroidMind directly from GitHub using stdio transport.

```json
{
  "mcpServers": {
    "droidmind": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hyperb1iss/droidmind",
        "droidmind",
        "--transport",
        "stdio" // The default and preferred mode for most IDE integrations
      ]
    }
  }
}
```

--------------------------------

### POST /android-shell

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/mcp-reference.md

Executes an arbitrary shell command on the device.

```APIDOC
## POST /android-shell

### Description
Executes a shell command string on the target Android device.

### Method
POST

### Endpoint
/android-shell

### Parameters
#### Request Body
- **serial** (string) - Required - Device serial number.
- **command** (string) - Required - The shell command string.
- **max_lines** (integer) - Optional - Limit output lines.
- **max_size** (integer) - Optional - Limit output characters.
```

--------------------------------

### Example Security Error Message

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/security.md

This message is displayed when DroidMind rejects a command due to security policies, such as attempting to use a disallowed command.

```text
Error: Command rejected for security reasons: Command 'setprop' is explicitly disallowed for security reasons.
```

--------------------------------

### Retrieve App-Specific Logs

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Shows the output format for logs filtered by a specific application package name.

```log
01-15 10:32:05.678  8765  4321 D com.example.myapp: Login successful for user 'bliss'
01-15 10:32:05.999  8765  4322 I com.example.myapp.NetworkService: Data sync initiated.
...
```

--------------------------------

### Analyze Java Heap Dump

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Provides the output format for a Java heap dump and the command to convert the resulting file for analysis.

```text
Capturing Java heap dump for process com.example.memoryhog...
...
Java heap dump saved to: /tmp/droidmind_heapdump_XXXXXX/com.example.memoryhog_java_heap_20230115_110530.hprof (5.75 MB)
```

```bash
hprof-conv /tmp/droidmind_heapdump_XXXXXX/com.example.memoryhog_java_heap_20230115_110530.hprof converted.hprof
```

--------------------------------

### Check Network Configuration

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Executes the 'ifconfig wlan0' command to check the network configuration for the Wi-Fi interface.

```python
await shell_command(
    serial="emulator-5554",
    command="ifconfig wlan0",
    ctx=context
)
```

--------------------------------

### Run DroidMind Server with SSE Transport

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/quickstart.md

Manually run the DroidMind server using `uvx` with SSE transport enabled. This is an alternative to stdio transport for specific use cases or client configurations.

```bash
uvx --from git+https://github.com/hyperb1iss/droidmind droidmind --transport sse --host localhost --port 4256
```

--------------------------------

### View Container Logs

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/docker.md

Commands to retrieve or follow logs from a running DroidMind container.

```bash
docker logs <container_name_or_id>
```

```bash
docker logs droidmind-server
```

```bash
docker logs -f droidmind-server
```

--------------------------------

### POST /android-app

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/mcp-reference.md

Performs various application management operations on an Android device.

```APIDOC
## POST /android-app

### Description
Manages applications on the device, including installation, uninstallation, and status retrieval.

### Method
POST

### Endpoint
/android-app

### Parameters
#### Request Body
- **serial** (string) - Required - Device serial number.
- **action** (string) - Required - The operation to perform (install_app, uninstall_app, start_app, stop_app, clear_app_data, list_packages, get_app_manifest, get_app_permissions, get_app_activities, get_app_info).
- **package** (string) - Optional - Package name.
- **apk_path** (string) - Optional - Local path to APK for install_app.
- **reinstall** (boolean) - Optional - For install_app.
- **grant_permissions** (boolean) - Optional - For install_app.
- **keep_data** (boolean) - Optional - For uninstall_app.
- **activity** (string) - Optional - Specific activity for start_app.
- **include_system_apps** (boolean) - Optional - For list_packages.
```

--------------------------------

### Enable ADB over TCP/IP

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/docker.md

Commands to enable wireless ADB debugging on an Android device connected via USB.

```bash
adb tcpip 5555
```

```bash
adb connect <device_ip_address>:5555
```

--------------------------------

### Upgrade Dependencies with uv lock

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/plan.md

Use this command to upgrade project dependencies and ensure CI stability. It's recommended to run this command regularly to keep dependencies current.

```bash
uv lock --upgrade
```

--------------------------------

### Get Android Device Properties

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Retrieve detailed properties of an Android device, identified by its serial number. Includes model, brand, Android version, SDK level, build number, and all system properties.

```python
# Get detailed device properties
# Requires: serial
# Returns: Model, Brand, Android Version, SDK Level, Build Number, and all system properties
await android_device(
    action="device_properties",
    ctx=context,
    serial="emulator-5554"
)
```

--------------------------------

### Retrieve General Device Logcat

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Shows the output format for general system logs retrieved from the device.

```log
01-15 10:30:01.123  1234  5678 I ActivityManager: Displayed com.example.app/.MainActivity: +100ms
01-15 10:30:01.456  8765  4321 D MyAppTag: User clicked the login button
...
```

--------------------------------

### Running Shell Commands

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/shell_commands.md

Execute shell commands on a specified Android device using the `shell_command` tool.

```APIDOC
## POST /shell_command

### Description
Executes a standard ADB shell command on a specified device.

### Method
POST

### Endpoint
/shell_command

### Parameters
#### Request Body
- **serial** (string) - Required - The target device's serial number.
- **command** (string) - Required - The shell command to execute.
- **max_lines** (integer) - Optional - Limits the number of lines returned. Positive for first N lines, negative for last N lines. Default is 1000.
- **max_size** (integer) - Optional - Limits the total size of the output returned in characters. Default is 100000.

### Request Example
```json
{
  "serial": "emulator-5554",
  "command": "ls -l /sdcard/",
  "max_lines": 100
}
```

### Response
#### Success Response (200)
- **output** (string) - The output of the executed shell command, potentially truncated.

#### Response Example
```json
{
  "output": "# Command Output from emulator-5554\n\n-rw-rw---- 1 u0_a123 sdcard_rw 1024 2023-01-15 10:00 myfile.txt\ndrwxrwx--x 1 u0_a123 sdcard_rw 0 2023-01-14 09:00 Download\n... (output may be truncated if it exceeds max_lines or max_size)"
}
```
```

--------------------------------

### POST /capture_bugreport

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Generates a comprehensive bug report archive for a specified device.

```APIDOC
## POST /capture_bugreport

### Description
Captures a full bug report including system logs and device state.

### Method
POST

### Endpoint
/capture_bugreport

### Parameters
#### Request Body
- **device_serial** (string) - Required - The serial identifier of the target device.
- **output_path** (string) - Optional - Local path on the server to save the ZIP file.
- **include_screenshots** (boolean) - Optional - Whether to include screenshots (default: True).
- **timeout_seconds** (integer) - Optional - Timeout duration in seconds (default: 300).
```

--------------------------------

### POST /android-ui

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/mcp-reference.md

Performs various UI interaction operations on an Android device based on the specified action.

```APIDOC
## POST /android-ui

### Description
Performs various UI interaction operations on an Android device.

### Method
POST

### Endpoint
/android-ui

### Parameters
#### Request Body
- **serial** (string) - Required - Device serial number.
- **action** (string) - Required - The UI operation to perform (tap, swipe, input_text, press_key, start_intent).
- **x** (integer) - Optional - X coordinate for tap.
- **y** (integer) - Optional - Y coordinate for tap.
- **start_x** (integer) - Optional - Starting X for swipe.
- **start_y** (integer) - Optional - Starting Y for swipe.
- **end_x** (integer) - Optional - Ending X for swipe.
- **end_y** (integer) - Optional - Ending Y for swipe.
- **duration_ms** (integer) - Optional - Duration for swipe.
- **text** (string) - Optional - Text for input_text.
- **keycode** (integer) - Optional - Keycode for press_key.
- **package** (string) - Optional - Package name for start_intent.
- **activity** (string) - Optional - Activity name for start_intent.
- **extras** (object) - Optional - Dictionary for start_intent.
```

--------------------------------

### Press Key on Android Device

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Simulates a key press on the Android device. Common keycodes include HOME (3), BACK (4), VOL_UP (24), VOL_DOWN (25), POWER (26), and MENU (82). Requires the 'keycode' parameter.

```python
# Press key (common keycodes: 3=HOME, 4=BACK, 24=VOL_UP, 25=VOL_DOWN, 26=POWER, 82=MENU)
# Requires: keycode
await android_ui(
    ctx=context,
    serial="emulator-5554",
    action="press_key",
    keycode=4  # BACK button
)
```

--------------------------------

### Capture Native Heap Dump

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Captures a native (C/C++) heap dump for a specified application package or process ID. Requires the 'package_or_pid' and 'native=True' parameters.

```python
# Capture native (C/C++) heap dump
await android_diag(
    ctx=context,
    serial="emulator-5554",
    action="dump_heap",
    package_or_pid="com.example.myapp",
    native=True
)
```

--------------------------------

### Uninstall Application

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/app_management.md

Remove an application by its package name. Set `keep_data=True` to retain the app's data and cache directories.

```python
droidmind.uninstall_app(device_serial='emulator-5554', package='com.example.oldapp', keep_data=False)
```

--------------------------------

### List Running Services

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Lists running services on the Android device using 'dumpsys activity services'. Output line count can be limited.

```python
await shell_command(
    serial="emulator-5554",
    command="dumpsys activity services",
    ctx=context,
    max_lines=200
)
```

--------------------------------

### Security Framework Imports

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Imports necessary components from DroidMind's security framework for command risk assessment and validation.

```python
from droidmind.security import (
    assess_command_risk,
    validate_shell_command,
    RiskLevel,
    ALLOWED_SHELL_COMMANDS,
    DISALLOWED_SHELL_COMMANDS,
    PROTECTED_PATHS
)
```

--------------------------------

### Output Handling and Truncation

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/shell_commands.md

Control the size of shell command output using `max_lines` and `max_size` parameters.

```APIDOC
## Output Truncation Parameters

To manage large command outputs, DroidMind provides:

- **`max_lines`**: Limits the number of lines returned.
  - Positive value (e.g., `100`): Returns the first 100 lines.
  - Negative value (e.g., `-50`): Returns the last 50 lines.
  - Default: `1000` lines.
  - `None`: No line limit (subject to `max_size`).

- **`max_size`**: Limits the total number of characters in the output.
  - Default: `100000` characters (approx. 100KB).

### Truncation Notification
If the output is truncated due to these limits, a notification will be appended to the output.

#### Example Truncated Output
```json
{
  "output": "...\n[Output truncated: 100000 chars, 1500 lines]"
}
```
```

--------------------------------

### Build DroidMind Docker Image

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/docker.md

Build the Docker image for DroidMind using the Dockerfile in the project's root directory. This command tags the image as 'droidmind:latest'.

```bash
docker build -t droidmind:latest .
```

--------------------------------

### android-device Tool

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Tool for managing Android device connections, reboots, and retrieving system properties.

```APIDOC
## android-device

### Description
Performs device management operations including listing, connecting, disconnecting, rebooting devices, and retrieving device properties.

### Parameters
#### Request Body
- **action** (string) - Required - The operation to perform: "list_devices", "connect_device", "disconnect_device", "device_properties", "reboot_device"
- **serial** (string) - Optional - The device serial identifier
- **ip_address** (string) - Optional - IP address for TCP/IP connection
- **port** (integer) - Optional - Port for TCP/IP connection (default: 5555)
- **mode** (string) - Optional - Reboot mode: "normal", "recovery", "bootloader"

### Response
#### Success Response (200)
- **result** (object) - Returns device list, properties, or operation status.
```

--------------------------------

### Transfer File to Device

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/example_queries.md

Upload a local file to a specified directory on the Android device using the `push_file` command. Ensure the source path is correct and the destination directory exists or is creatable.

```bash
push_file /Users/bliss/Desktop/new_config.xml /sdcard/AppConfig/ your_device_serial
```

--------------------------------

### Download File from Android Device

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Download a file from an Android device to the server using the file_operations tool. Requires the source path on the device and the destination path on the server.

```python
# Download file from device to server
# Requires: device_path (source), local_path (destination)
await file_operations(
    serial="emulator-5554",
    action="pull_file",
    ctx=context,
    device_path="/sdcard/screenshots/screen.png",
    local_path="/home/user/screen.png"
)
```

--------------------------------

### Retrieve Device Properties

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/device_diagnostics.md

Displays the raw property output format for a connected Android device.

```properties
[ro.product.model]: [sdk_gphone64_x86_64]
[ro.product.brand]: [google]
[ro.build.version.release]: [12]
[ro.build.version.sdk]: [31]
[ro.build.display.id]: [SE1A.220601.001]
[ro.product.manufacturer]: [Google]
[persist.sys.timezone]: [America/Los_Angeles]
...
(many more properties)
```

--------------------------------

### POST /android-file

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/mcp-reference.md

Performs various file and directory operations on an Android device.

```APIDOC
## POST /android-file

### Description
Performs a variety of file and directory operations on an Android device based on the specified action.

### Method
POST

### Endpoint
/android-file

### Parameters
#### Request Body
- **serial** (string) - Required - Device serial number.
- **action** (string) - Required - The operation to perform (list_directory, push_file, pull_file, delete_file, create_directory, file_exists, read_file, write_file, file_stats).
- **path** (string) - Optional - General device path.
- **local_path** (string) - Optional - Server-side path for push/pull operations.
- **device_path** (string) - Optional - Device-side path.
- **content** (string) - Optional - Text content for write_file.
- **max_size** (integer) - Optional - Max size for read_file.

### Response
#### Success Response (200)
- **result** (any) - The output of the file operation (e.g., boolean for file_exists).
```

--------------------------------

### android_ui

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Performs various UI automation actions on an Android device.

```APIDOC
## android_ui

### Description
Executes UI automation actions such as swipes, text input, key presses, and intent launching.

### Parameters
- **ctx** (context) - Required - The execution context.
- **serial** (string) - Required - The device serial number.
- **action** (string) - Required - The action to perform (swipe, input_text, press_key, start_intent).
- **start_x** (int) - Optional - Starting X coordinate for swipe.
- **start_y** (int) - Optional - Starting Y coordinate for swipe.
- **end_x** (int) - Optional - Ending X coordinate for swipe.
- **end_y** (int) - Optional - Ending Y coordinate for swipe.
- **duration_ms** (int) - Optional - Duration of swipe in milliseconds.
- **text** (string) - Optional - Text to input.
- **keycode** (int) - Optional - Keycode to press.
- **package** (string) - Optional - Package name for intent.
- **activity** (string) - Optional - Activity name for intent.
- **extras** (dict) - Optional - Intent extras.
```

--------------------------------

### Check Storage Space

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Executes the 'df -h' command to check the storage space usage on the Android device.

```python
await shell_command(
    serial="emulator-5554",
    command="df -h",
    ctx=context
)
```

--------------------------------

### Run DroidMind with Explicit SSE Configuration

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/docker.md

Manually configure DroidMind to use SSE transport, listen on all container interfaces (0.0.0.0), and bind to port 4256. This provides explicit control over the server's network settings.

```bash
docker run -d -p 4256:4256 --name droidmind-server droidmind:latest droidmind --transport sse --host 0.0.0.0 --port 4256
```

--------------------------------

### android-file Tool

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Tool for performing file and directory operations on Android devices.

```APIDOC
## android-file

### Description
Performs comprehensive file and directory operations on Android devices, including listing, pushing, pulling, reading, writing, and managing files.

### Parameters
#### Request Body
- **action** (string) - Required - The operation: "list_directory", "push_file", "pull_file", "read_file", "write_file", "file_exists"
- **serial** (string) - Required - The device serial identifier
- **path** / **device_path** (string) - Required - Target path on the device
- **local_path** (string) - Optional - Source or destination path on the host server
- **content** (string) - Optional - Text content for write operations
- **max_size** (integer) - Optional - Max size for read operations (default: 100KB)

### Response
#### Success Response (200)
- **result** (any) - Returns file contents, directory listings, or boolean status.
```

--------------------------------

### POST /android-screenshot

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/mcp-reference.md

Captures a screenshot from the specified Android device.

```APIDOC
## POST /android-screenshot

### Description
Captures a screenshot from the device.

### Method
POST

### Endpoint
/android-screenshot

### Parameters
#### Request Body
- **serial** (string) - Required - Device serial number.
- **quality** (integer) - Optional - JPEG quality (1-100, default 75).
```

--------------------------------

### Run DroidMind with Custom Stdio Options

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/docker.md

Execute the DroidMind container in interactive mode and pass custom options to the droidmind executable for stdio transport. This is less common for typical AI assistant usage.

```bash
docker run -it --rm --name droidmind-cli droidmind:latest droidmind --your-stdio-options
```

--------------------------------

### List Directory Contents on Android

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Use the file_operations tool to list the contents of a specified directory on an Android device. Requires the device serial and the path to the directory.

```python
# List directory contents
# Requires: path (directory path on device)
await file_operations(
    serial="emulator-5554",
    action="list_directory",
    ctx=context,
    path="/sdcard/Download"
)
```

--------------------------------

### Retrieve App-Specific Logs

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Fetches logs for a specific application package on the Android device. Requires the 'package' name and optionally the number of 'lines' to retrieve.

```python
# Get logs for specific app
# Requires: package
# Optional: lines
await android_log(
    serial="emulator-5554",
    action="get_app_logs",
    ctx=context,
    package="com.example.myapp",
    lines=500
)
```

--------------------------------

### List Android Devices

Source: https://context7.com/hyperb1iss/droidmind/llms.txt

Use the android_device tool to list all connected Android devices. Returns a formatted list including model, serial, and Android version.

```python
# List all connected Android devices
# Action: list_devices
# Returns formatted list with model, serial, and Android version
await android_device(action="list_devices", ctx=context)
```

--------------------------------

### Run DroidMind via CLI

Source: https://github.com/hyperb1iss/droidmind/blob/main/README.md

Execute DroidMind using different transport protocols for terminal or server-based interactions.

```bash
droidmind --transport stdio
```

```bash
droidmind --transport sse
```

--------------------------------

### Device Connection & Management - android-device

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/mcp-reference.md

This tool allows for various device management operations on Android devices, including listing, connecting, disconnecting, and rebooting.

```APIDOC
## POST /tools/android-device

### Description
Performs various device management operations on Android devices.

### Method
POST

### Endpoint
/tools/android-device

### Parameters
#### Request Body
- **ctx** (object) - Required - MCP Context.
- **action** (string) - Required - Specifies the operation. One of: `list_devices`, `connect_device`, `disconnect_device`, `device_properties`, `reboot_device`.
- **serial** (string) - Optional - Device serial number. See specific `action` for usage.
- **ip_address** (string) - Optional - IP address for `connect_device`.
- **port** (integer) - Optional - Port for `connect_device` (default 5555).
- **mode** (string) - Optional - Reboot mode for `reboot_device` (default `normal`; e.g., `recovery`, `bootloader`).

### Request Example
```json
{
  "ctx": {},
  "action": "list_devices"
}
```

### Response
#### Success Response (200)
- **devices** (array) - List of connected devices and their information (for `list_devices`).
- **message** (string) - Confirmation message (for other actions).

#### Response Example
```json
{
  "devices": [
    {
      "serial": "emulator-5554",
      "state": "device",
      "model": "Android SDK built for x86",
      "version": "30"
    }
  ]
}
```
```

--------------------------------

### List Directory Contents on Android Device

Source: https://github.com/hyperb1iss/droidmind/blob/main/docs/user_manual/file_system.md

Use this to explore the file system of a connected Android device. Specify the directory path and the device serial number in your prompt.

```text
List the contents of `/sdcard/Download/` on `emulator-5554`.
```

```text
Show me the files and folders in `/data/local/tmp` on `your_device_serial`.
```

```text
What's inside the `/sdcard/Pictures` directory on `emulator-5554`?
```