DeepADB

MCP (Model Context Protocol) server for AI agents that need to inspect, control, test, and diagnose Android devices through ADB—or directly on-device through Termux.

209 tools, 5 resources, and 4 prompts across 49 modules—from UI automation and application management to logs, network capture, baseband, firmware, security, and hardware diagnostics.

Get started

DeepADB runs as a local MCP server. It uses ADB by default and automatically switches to direct execution when it detects Termux on an Android device.

git clone https://github.com/fullread/DeepADB.git
cd DeepADB
npm ci
npm run build
npm start

Add `build/index.js` to your MCP client configuration, then begin with these workflows:

For a guided local connection, see Claude Code Configuration. Read SECURITY.md before exposing HTTP, WebSocket, or GraphQL transports beyond loopback.

Architecture

┌──────────────────────────────────────────────────┐
│                   MCP Client                     │
│             (Claude Code / claude.ai)            │
└──────────────────────┬───────────────────────────┘
                       │ stdio (JSON-RPC) or HTTP/SSE or WebSocket
┌──────────────────────▼───────────────────────────┐
│               DeepADB Server                     │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │           Tool Modules (49)                 │ │
│  │  device │ shell │ packages │ files │ logs   │ │
│  │  diagnostics │ ui │ build │ health          │ │
│  │  wireless │ control │ logcat-watch          │ │
│  │  forwarding │ screen-record │ emulator      │ │
│  │  testing │ multi-device │ snapshot          │ │
│  │  network-capture │ ci │ plugins │ baseband  │ │
│  │  accessibility │ regression                 │ │
│  │  device-farm │ registry │ at-commands       │ │
│  │  screenshot-diff │ workflow │ sensors       │ │
│  │  split-apk │ mirroring │ test-gen           │ │
│  │  ota-monitor │ ril-intercept                │ │
│  │  device-profiles │ firmware-analysis        │ │
│  │  workflow-market │ selinux-audit            │ │
│  │  thermal-power │ network-discovery          │ │
│  │  input-gestures │ wireless-firmware         │ │
│  │  app-network │ database-inspector           │ │
│  │  runtime-audit │ wear                       │ │
│  ├─────────────────────────────────────────────┤ │
│  │  Resources (5) │ Prompts (4)                │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │          ToolContext (unified DI)           │ │
│  │  server │ bridge │ deviceManager            │ │
│  │  logger │ security │ config                 │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │           Middleware Layer                  │ │
│  │  OutputProcessor │ SecurityMiddleware       │ │
│  │  InputSanitizer │ Logger (stderr-safe)      │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │         Bridge Layer (auto-detect)          │ │
│  │                                             │ │
│  │  ┌─────────────┐    ┌────────────────────┐  │ │
│  │  │  ADB Bridge  │ OR │  Local Bridge      │ │ │
│  │  │  (PC mode)   │    │  (on-device mode)  │ │ │
│  │  │  via adb.exe │    │  via sh/su direct  │ │ │
│  │  └──────┬───────┘    └────────┬───────────┘ │ │
│  │         │                     │             │ │
│  │  Retry │ Timeout │ Cache │ Serial routing   │ │
│  └─────────┼─────────────────────┼─────────────┘ │
└────────────┼─────────────────────┼───────────────┘
             │                     │
     ┌───────▼───────┐    ┌───────▼───────┐
     │  ADB Binary   │    │   sh / su     │
     │  (USB/WiFi)   │    │   (local)     │
     └───────┬───────┘    └───────┬───────┘
             │                    │
       ┌─────▼────────────────────▼─────┐
       │          Android Device        │
       └────────────────────────────────┘

Dual-Mode Architecture

DeepADB operates in two modes, auto-detected at startup:

ADB Mode (default) — PC-side bridge

AI Agent (PC) ←→ MCP ←→ DeepADB (PC) ←→ ADB (USB) ←→ Android Device

Standard mode: DeepADB runs on a PC/Mac/Linux host and communicates with the device over USB via ADB. The complete 209-tool surface is registered through the ADB bridge with automatic retry on transient failures; environment-specific tools report their capability requirements when a host cannot run them.

On-Device Mode — direct local execution

AI Agent (Termux) ←→ MCP (stdio/HTTP) ←→ DeepADB (Termux) ←→ sh/su (local)

When DeepADB runs directly on the Android device (e.g., inside Termux), it auto-detects the environment and switches to `LocalBridge`. Commands execute directly via `sh`/`su` — no ADB server, no USB, no serialization overhead. The same 209-tool MCP surface is registered, with capability-aware guidance when an optional on-device binary such as `sqlite3` is unavailable.

v1.1.4 host hardware validation: the full Pixel 6a / Android 16 regression completed with 604 passed, 0 failed, and 17 expected environment-specific skips (621 total). This includes live AT/OK validation on `/dev/umts_router`, a guarded read-only SQLite schema snapshot with cleanup, the unified runtime audit, per-app route context, and the single-device Wear preflight. The skips are the five on-device-only QEMU checks plus twelve Windows-host or unavailable-`tcpdump` security checks.

v1.1.3 hardware baseline: validated on a Pixel 6a (Android 16, Termux + Magisk + QEMU 10.2.1) across a four-cell test matrix — host (ADB) and on-device (LocalBridge), each with and without a device PIN — with 0 failures in every cell. The v1.1.3 suite contained 577 tests in the host/ADB configuration and 613 on-device; the difference is the QEMU virtualization and Alpine VM-boot suites, which run only on-device:

• ADB mode, no PIN: 556 passed / 0 failed / 21 skipped (577 total). Skips: 5 QEMU (on-device only), 7 gracefulKill unit tests (require POSIX signals, skipped on the Windows host), 3 tcpdump sanitization (tcpdump is root-only and unreachable over a non-root ADB shell), 2 host-shell round-trips (require a POSIX /bin/sh), 4 screen-state (require DA_TEST_PIN).
• ADB mode, with PIN: 560 passed / 0 failed / 17 skipped (577 total). The 4 screen-state tests unlock and run.
• On-device mode, no PIN: 606 passed / 0 failed / 7 skipped (613 total). All QEMU tests run, including Alpine Linux VM boot with KVM acceleration, big.LITTLE CPU topology detection, guest ADB connectivity error handling, and clean VM shutdown; the tcpdump and gracefulKill suites also run here (root + POSIX). Skips: 3 QEMU setup steps that no-op when the Alpine kernel/initrd/disk are already cached, 4 screen-state (require PIN).
• On-device mode, with PIN: 610 passed / 0 failed / 3 skipped (613 total). Every test enabled by the environment runs; the 3 skips are the cached-VM setup steps.

Privilege escalation: In ADB mode, all shell commands run as uid=2000 (the `shell` user) which has system-level permissions. In Termux, commands run as a regular app user. LocalBridge automatically elevates privileged commands through `su` when root (Magisk) is available:

• Command allowlist: 16 system commands (`settings`, `dumpsys`, `am`, `input`, `screencap`, `screenrecord`, `uiautomator`, `app_process`, `getenforce`, `setenforce`, `cmd`, `pm`, `wm`, `svc`, `ip`, `ifconfig`) are routed through `su -c` to match ADB-mode behavior.
• Path-based elevation: Commands referencing `/sdcard`, `/storage`, or `/system/` paths are elevated to bypass Android scoped storage restrictions.
• Root detection: Cached after a single `su -c id` probe at first use. Graceful degradation when root is unavailable.
• The elevation allowlist is frozen (`ReadonlySet` + `Object.freeze`) — not configurable via environment variables or runtime API.

Auto-detection: Checks for `/system/build.prop` (present on all Android devices, never on hosts). Override with `DA_LOCAL=true` or `DA_LOCAL=false`.

On-device setup (Termux):

pkg install nodejs-lts git
git clone  && cd deepadb
npm install && npm run build
npm start                              # stdio — for local AI agents (Claude Code, OpenCode)
DA_HTTP_PORT=3000 npm start            # HTTP/SSE — for remote AI access over WiFi

Claude Code Configuration

{
  "mcpServers": {
    "deepadb": {
      "command": "node",
      "args": ["/path/to/DeepADB/build/index.js"]
    }
  }
}

Available Tools (209)

Start with the capability area that matches your task; the complete reference remains below.

Complete tool reference

Health (1 tool)

• `adb_health_check` — Comprehensive toolchain validation: ADB binary, server, device connection, authorization, root access, and storage writability

Runtime Audit (1 tool)

• `adb_runtime_audit` — Unified read-only readiness audit for transport, Android userspace, root, SELinux, storage, command capabilities, UI/network diagnostics, SQLite, modem nodes, and Wear prerequisites

Device (3 tools)

• `adb_devices` — List all connected devices with state, model, and product info
• `adb_device_info` — Detailed device properties (model, OS, SDK, build, security patch, ABI)
• `adb_getprop` — Read a specific system property or dump all properties

Shell (2 tools)

• `adb_shell` — Execute arbitrary shell commands with configurable timeout (security-checked)
• `adb_root_shell` — Execute commands as root via su (requires rooted device, security-checked)

Packages (12 tools)

• `adb_install` — Install APK with replace/downgrade options
• `adb_uninstall` — Remove package with optional data retention
• `adb_list_packages` — List packages filtered by name or type (all/system/third-party)
• `adb_package_info` — Detailed package info (version, permissions, paths)
• `adb_clear_data` — Clear all app data and cache
• `adb_grant_permission` — Grant a runtime permission to a package
• `adb_revoke_permission` — Revoke a runtime permission from a package (reset permission state for testing denial flows)
• `adb_list_permissions` — List all declared and granted permissions for a package, filterable by granted/denied
• `adb_force_stop` — Force-stop an app immediately
• `adb_start_app` — Launch an app by package name (resolves launcher activity)
• `adb_restart_app` — Force-stop then re-launch in one call (configurable delay)
• `adb_resolve_intents` — Discover registered activities, services, and receivers with intent filters

Room & SQLite Inspection (1 tool)

• `adb_sqlite_inspect` — Package-scoped database listing, schema inspection, and validated read-only SQL with hard row/output caps. Prefers `run-as`, falls back to root, rejects symbolic-link database/WAL files, uses device `sqlite3` when present, and otherwise deletes a private, bounded host-side snapshot after inspection

Files (18 tools)

• `adb_push` — Push local file to device (hard-blocked kernel paths, fs-type awareness, storage reporting)
• `adb_pull` — Pull file from device to local filesystem
• `adb_ls` — List device directory contents (simple or detailed)
• `adb_cat` — Read text file from device with optional line limit
• `adb_file_write` — Create or overwrite text files via heredoc (buffer limit warning, fs-aware, post-verify)
• `adb_find` — Search for files by name/pattern with depth control and result capping
• `adb_file_stat` — File metadata: size, permissions, timestamps, ownership, SELinux context
• `adb_file_checksum` — SHA-256/SHA-1/MD5 hash with size-based timeout estimation
• `adb_mkdir` — Create directories with parent creation (-p), hard-blocked kernel paths
• `adb_rm` — Delete files/directories with depth-based recursive protection and symlink resolution
• `adb_file_move` — Move/rename with source depth protection and post-verify
• `adb_file_copy` — Copy with pre-flight size+space check and post-verify size match
• `adb_file_chmod` — Change permissions (Zod-validated octal mode, depth-based recursive protection)
• `adb_file_touch` — Create empty files or update timestamps (explicit timestamp support)
• `adb_file_fsinfo` — Filesystem report: type, mount, capacity, capabilities, SELinux, limitations
• `adb_file_chown` — Change ownership (root required, depth-based recursive protection)
• `adb_grep` — Search file contents with fixed-string default, recursive depth control, result capping
• `adb_file_replace` — Find/replace text in files (sed-backed, proper escaping, backup option)

Logs — Snapshots (3 tools)

• `adb_logcat` — Filtered logcat snapshot with tag, priority, grep, and buffer selection
• `adb_logcat_clear` — Clear all logcat buffers
• `adb_logcat_crash` — Crash buffer log snapshot

Logs — Persistent Watchers (4 tools)

• `adb_logcat_start` — Start a background logcat watcher with ring buffer accumulation
• `adb_logcat_poll` — Retrieve new lines since last poll from a running watcher
• `adb_logcat_stop` — Stop a watcher session (or all sessions)
• `adb_logcat_sessions` — List all active watcher sessions with stats

Diagnostics (9 tools)

• `adb_dumpsys` — Run dumpsys for any service (or list all services)
• `adb_telephony` — Cell info, signal strength, and network registration (parallel query)
• `adb_battery` — Battery status, level, temperature, and charging info
• `adb_network` — WiFi, cellular, and IP connectivity (parallel query)
• `adb_top` — CPU and memory usage snapshot
• `adb_perf_snapshot` — Parallel memory, frame stats, and CPU profiling for a package
• `adb_bugreport` — Full bug report zip capture (device state, logs, system info)
• `adb_crash_logs` — ANR traces and tombstone crash dumps from /data/anr/ and /data/tombstones/
• `adb_heap_dump` — Capture heap dump (.hprof) from a running process for memory analysis

Per-App Route Context (1 tool)

• `adb_app_route_context` — Resolve an installed package to its UID and correlate its effective `ip rule` ranges, route tables, network policy, VPN, and default-network state without changing routes or policy

UI (10 tools)

• `adb_screencap` — Take screenshot with filename sanitization, saves locally
• `adb_screencap_annotated` — Screenshot with UI element bounding boxes and numbered labels composited onto the PNG. Returns annotated image path plus a text legend. Ideal for LLM workflows that reference elements by number
• `adb_current_activity` — Get focused activity and top window stack
• `adb_input` — Send tap, swipe, text, or keyevent input
• `adb_start_activity` — Launch activities by intent or component name
• `adb_ui_dump` — Dump full UI hierarchy. Supports three output formats: `text` (default, human-readable), `tsv` (compact tab-separated for token-efficient automation loops), `xml` (raw uiautomator XML)
• `adb_ui_find` — Search UI hierarchy by text, resource-id, or content-description (returns tap coordinates)
• `adb_screen_state` — Combined screen state in one call: foreground activity, screen dimensions and density, orientation, battery level, and a TSV list of interactive elements. Replaces 3–4 separate tool calls
• `adb_screenrecord_start` — Start recording the device screen (1-180s, stored on device)
• `adb_screenrecord_stop` — Stop recording and pull the mp4 video file locally

Device Control (9 tools)

• `adb_airplane_mode` — Toggle airplane mode with broadcast and verification
• `adb_airplane_cycle` — Cycle airplane mode on/off to force cellular re-registration
• `adb_wifi` — Enable or disable WiFi
• `adb_mobile_data` — Enable or disable mobile data
• `adb_location` — Set location mode (off/sensors/battery/high)
• `adb_screen` — Wake, sleep, toggle, lock, or unlock the screen. Lock verifies keyguard state via `dumpsys window`. Unlock uses `wm dismiss-keyguard` (works for swipe keyguards); supply `pin` to perform the full PIN entry sequence: wakes screen, swipes up to reveal keypad, types PIN, confirms, and verifies the keyguard sleep token was released
• `adb_settings_get` — Read any Android setting from system/secure/global namespace
• `adb_settings_put` — Write any Android setting with read-back verification
• `adb_reboot` — Reboot device (normal, recovery, or bootloader mode)

Wireless Debugging (4 tools)

• `adb_pair` — Pair with device over WiFi using pairing code
• `adb_connect` — Connect to device over WiFi/TCP
• `adb_disconnect` — Disconnect wireless device(s)
• `adb_tcpip` — Switch USB device to TCP/IP mode (auto-detects device IP)

Port Forwarding (8 tools)

• `adb_forward` — Forward a local port to a device port (host → device)
• `adb_reverse` — Reverse-forward a device port to the host (device → host)
• `adb_forward_list` — List all active forward and reverse port mappings
• `adb_forward_remove` — Remove a port forward or all forwards
• `adb_reverse_remove` — Remove a reverse forward or all reverse forwards
• `adb_tunnel_open` — Open a managed tunnel with opaque ID. Auto-picks a free host port for forward direction when omitted; registers cleanup so the tunnel is removed on server exit
• `adb_tunnel_list` — List active managed tunnels (those opened via adb_tunnel_open). Optional device filter; shows ID, direction, endpoints, and age
• `adb_tunnel_close` — Close a managed tunnel by ID, or close all at once with id="all"

Emulator Management (3 tools)

• `adb_avd_list` — List available AVDs (PC mode) or detect KVM/QEMU virtualization capabilities (on-device mode)
• `adb_emulator_start` — Launch an AVD with headless, cold boot, and GPU options (PC mode) or report QEMU alternative (on-device mode)
• `adb_emulator_stop` — Gracefully shut down a running emulator

QEMU/KVM Virtualization (8 tools)

• `adb_qemu_setup` — Check and install QEMU for on-device virtualization. Verifies KVM, reports host CPU/RAM, installs via Termux pkg
• `adb_qemu_images` — Manage VM disk images: list, create (qcow2/raw), delete. Path containment verification prevents traversal
• `adb_qemu_start` — Boot a KVM-accelerated VM with dynamic resource allocation. Auto-detects optimal CPUs (total minus 1, reserving one for host) and memory (65% of physical RAM). Supports kernel/initrd/append for Android boot, ADB port forwarding
• `adb_qemu_stop` — Stop a running VM (graceful SIGTERM or force SIGKILL). Auto-disconnects guest ADB before killing. Reports running VMs if no name given
• `adb_qemu_status` — Full status: KVM/QEMU availability, host resource budget, running VMs with PID/resources/uptime/ports/ADB connection state, image inventory
• `adb_qemu_connect` — Connect to a running VM's guest ADB service. Restricted to localhost only — port derived from running VM state, never user input. Enables multi-device tools to operate on guest VMs
• `adb_qemu_disconnect` — Disconnect from a guest VM's ADB service. Clears connection state and removes guest from device list
• `adb_qemu_guest_shell` — Execute shell commands on a guest VM via ADB. Subject to security middleware. Guest serial derived internally — no user-supplied host/IP reaches the ADB binary

Test Sessions (3 tools)

• `adb_test_session_start` — Start a named test session with organized output directory
• `adb_test_step` — Capture a numbered step with screenshot and logcat into the session
• `adb_test_session_end` — End session, write summary manifest, return directory path

Multi-Device Orchestration (4 tools)

• `adb_multi_shell` — Execute a command on all/selected devices in parallel (security-checked)
• `adb_multi_install` — Install an APK across multiple devices simultaneously
• `adb_multi_compare` — Run a command on all devices and highlight output differences
• `adb_multi_test` — Comparative test workflow: run predefined diagnostic profiles (firmware/security/network/identity/full) or custom command lists across all devices including QEMU guests, compare per-check, report matches and differences

Wear Data Layer (1 tool)

• `adb_wear_datalayer_preflight` — Read-only phone/watch role, Google Play services, Bluetooth, optional package, companion-association, and Data Layer service preflight; pairing identifiers are intentionally omitted

Input Gestures & UI Automation (15 tools)

• `adb_input_drag` — Drag from point A to point B (uses `draganddrop` with swipe fallback for older Android)
• `adb_input_fling` — High-velocity fling gesture for momentum-scrolling through lists and paged views (configurable duration 20-200ms)
• `adb_input_long_press` — Long press at coordinates with configurable hold duration
• `adb_input_double_tap` — Double tap with configurable interval between taps
• `adb_input_text` — Dedicated text input with space/special character handling
• `adb_open_url` — Open a URL on the device via VIEW intent
• `adb_orientation` — Get or set screen orientation (auto/portrait/landscape/reverse)
• `adb_clipboard` — Read or write device clipboard
• `adb_input_pinch` — Multi-touch pinch (zoom out) or spread (zoom in) gesture. Two fingers move symmetrically around a center point. Layered injection: parallel `input swipe` (universal, no root) or raw `sendevent` MT Type B protocol (true multi-touch, root required). Auto-detects touchscreen device and capabilities via `getevent -p`. Configurable center, radius, duration, angle, and interpolation steps
• `adb_tap_element` — Find element by text/resource-id/content-description and tap its center
• `adb_wait_element` — Poll UI hierarchy until an element appears or disappears (configurable timeout/poll interval)
• `adb_wait_stable` — Poll until consecutive UI dumps match (screen stabilization after transitions)
• `adb_scroll_until` — Scroll repeatedly until a target element is found, with optional auto-tap
• `adb_screenshot_compressed` — Capture screenshot with size/quality metadata for token-efficient workflows
• `adb_batch_actions` — Execute multiple input actions (tap/swipe/fling/long_press/double_tap/keyevent/text/drag/pinch/back/home/sleep) in a single tool call with security validation

Device Awareness (3 tools)

• `adb_screen_size` — Screen resolution, display density (DPI), aspect ratio, and DP width in one call
• `adb_device_state` — Combined snapshot: battery level/status/temp, network type, WiFi state, screen on/off, orientation, foreground activity
• `adb_notifications` — Parse active notifications with package, title, text, importance, channel, flags, and timestamp (filterable by package)

Snapshot/Restore (3 tools)

• `adb_snapshot_capture` — Save comprehensive device state (packages, settings, properties) to JSON
• `adb_snapshot_compare` — Diff current state against a saved snapshot (added/removed packages, changed settings)
• `adb_snapshot_restore_settings` — Restore global/secure settings from a saved snapshot

Network Capture (3 tools)

• `adb_tcpdump_start` — Start background packet capture via tcpdump (requires root)
• `adb_tcpdump_stop` — Stop capture and pull pcap file locally for Wireshark analysis
• `adb_network_connections` — Show active TCP/UDP connections (ss/netstat with /proc/net fallback)

CI/CD Integration (3 tools)

• `adb_ci_wait_boot` — Wait for device/emulator to fully boot with configurable timeout
• `adb_ci_device_ready` — Structured pass/fail readiness check (boot, PM, screen, network, disk)
• `adb_ci_run_tests` — Run instrumented tests via `am instrument` with parsed pass/fail results

Baseband/Modem (6 tools)

• `adb_baseband_info` — Modem firmware, RIL implementation, chipset, SIM configuration (dual SIM detection with per-slot state), network registration. IMEI retrieval is opt-in only (`includeImei=true`)
• `adb_cell_identity` — Cell ID (CID), TAC/LAC, EARFCN, PCI, PLMN from dumpsys phone for cellular network analysis
• `adb_signal_detail` — RSRP, RSRQ, SINR, RSSI, timing advance — raw radio measurements for signal analysis
• `adb_neighboring_cells` — All visible LTE/5G/WCDMA/GSM cells with identities and signal strengths
• `adb_carrier_config` — Carrier configuration dump, carrier ID, preferred APN
• `adb_modem_logs` — RIL radio buffer, telephony framework, RILJ/RILC, kernel dmesg (root) modem logs

Accessibility Auditing (3 tools)

Project Structure

DeepADB/
├── src/
│   ├── index.ts                # Entry point — stdio, HTTP/SSE, WebSocket, or GraphQL transport
│   ├── server.ts               # MCP server wiring, config, module registration (exports CreateServerResult)
│   ├── http-transport.ts       # HTTP/SSE transport server for browser clients
│   ├── ws-transport.ts         # WebSocket transport (optional `ws` peer dependency)
│   ├── graphql-api.ts          # GraphQL API endpoint (optional `graphql` peer dependency)
│   ├── tool-context.ts         # Unified dependency bundle (ToolContext interface)
│   ├── bridge/
│   │   ├── adb-bridge.ts       # Core ADB subprocess wrapper, retry logic, error types
│   │   ├── local-bridge.ts     # On-device direct execution bridge with privilege escalation (Termux/local mode)
│   │   └── device-manager.ts   # Device discovery, TTL cache, serial routing
│   ├── tools/
│   │   ├── health.ts           # Toolchain health check (1 tool)
│   │   ├── runtime-audit.ts    # Unified read-only runtime readiness audit (1 tool)
│   │   ├── device.ts           # Device info and properties (3 tools)
│   │   ├── shell.ts            # Shell and root command execution (2 tools)
│   │   ├── packages.ts         # App lifecycle, install, permissions, intents (12 tools)
│   │   ├── database-inspector.ts # Package-scoped read-only Room/SQLite inspection (1 tool)
│   │   ├── files.ts            # File operations — push, pull, write, find, grep, replace, stat, checksum, chmod, chown, touch, fsinfo (18 tools)
│   │   ├── logs.ts             # Logcat snapshots — filtered (3 tools)
│   │   ├── logcat-watch.ts     # Persistent logcat with ring buffer and poll (4 tools)
│   │   ├── diagnostics.ts      # dumpsys, telephony, battery, network, perf, bugreport, crash logs, heap dump (9 tools)
│   │   ├── ui.ts               # Screenshots, input, activity, UI hierarchy, annotated screencap, screen state (8 tools)
│   │   ├── input-gestures.ts   # Drag, long press, double tap, text, URL, orientation, clipboard, tap-element, wait-element, wait-stable, scroll-until, compressed screenshot, batch actions, fling, pinch, screen size, device state, notifications (18 tools)
│   │   ├── screen-record.ts    # Screen video recording start/stop (2 tools)
│   │   ├── control.ts          # Airplane, WiFi, data, location, screen, settings, reboot (9 tools)
│   │   ├── wireless.ts         # WiFi pairing, connect, disconnect, TCP/IP (4 tools)
│   │   ├── forwarding.ts       # Port forwarding — forward, reverse, list, remove, managed tunnels with auto-port-pick (8 tools)
│   │   ├── emulator.ts         # AVD list, start, stop with on-device KVM/QEMU detection (3 tools)
│   │   ├── qemu.ts             # QEMU/KVM VM management — setup, images, start, stop, status, guest ADB connect/disconnect/shell (8 tools)
│   │   ├── testing.ts          # Structured test sessions with numbered steps (3 tools)
│   │   ├── multi-device.ts     # Multi-device shell, install, compare, comparative testing (4 tools)
│   │   ├── snapshot.ts         # Device state capture, compare, restore (3 tools)
│   │   ├── network-capture.ts  # tcpdump start/stop, network connections (3 tools)
│   │   ├── ci.ts               # CI wait-boot, device-ready, run-tests (3 tools)
│   │   ├── plugins.ts          # Plugin loader, info, and dynamic tool loading (2 tools)
│   │   ├── baseband.ts         # Modem/baseband inspection and radio diagnostics (6 tools)
│   │   ├── accessibility.ts    # Automated WCAG accessibility auditing (3 tools)
│   │   ├── regression.ts       # Performance baseline and regression detection (3 tools)
│   │   ├── device-farm.ts      # Firebase Test Lab integration via gcloud (3 tools)
│   │   ├── registry.ts         # Community plugin registry search/install (3 tools)
│   │   ├── at-commands.ts      # AT command modem interface, Shannon session, cross-validation (6 tools)
│   │   ├── screenshot-diff.ts  # Visual regression — screenshot baseline/diff (3 tools)
│   │   ├── workflow.ts         # Declarative workflow orchestration engine (3 tools)
│   │   ├── split-apk.ts        # App bundles, split APKs, APEX modules (4 tools)
│   │   ├── mirroring.ts        # Live screen mirroring via scrcpy (3 tools)
│   │   ├── test-gen.ts         # Automated test workflow generation (3 tools)
│   │   ├── ota-monitor.ts      # OTA update monitoring and fingerprinting (3 tools)
│   │   ├── ril-intercept.ts    # RIL message interception from radio buffer (3 tools)
│   │   ├── device-profiles.ts  # Device profile library with built-in entries (3 tools)
│   │   ├── firmware-analysis.ts # Modem firmware version parsing and diffing (3 tools)
│   │   ├── workflow-market.ts  # Workflow marketplace — search, install, export (3 tools)
│   │   ├── selinux-audit.ts    # SELinux status, AVC denials, permission auditing (3 tools)
│   │   ├── thermal-power.ts    # Thermal zones, CPU frequency, battery drain (3 tools)
│   │   ├── network-discovery.ts # ADB-over-network scanning and auto-connect (3 tools)
│   │   ├── app-network.ts      # Per-app UID routing and network-policy context (1 tool)
│   │   ├── wear.ts             # Wear OS Data Layer phone/watch preflight (1 tool)
│   │   ├── sensors.ts          # Hardware sensor enumeration, IIO power monitor reading (2 tools)
│   │   ├── result-handles.ts   # Tempdir-backed result handle store — list, drop, drop-all (3 tools) + the result://{tool}/{name} resource
│   │   ├── wireless-firmware.ts # WiFi, Bluetooth, NFC, GPS firmware identification (4 tools)
│   │   ├── build.ts            # Gradle build and install (2 tools)
│   │   ├── resources.ts        # MCP Resources — 4 device-state surfaces: device://info|battery|telephony|list (5th, result://, lives in result-handles.ts)
│   │   └── prompts.ts          # MCP Prompts — workflow templates (4 prompts)
│   ├── middleware/
│   │   ├── auth.ts             # Bearer token authentication for network transports (DA_AUTH_TOKEN)
│   │   ├── output-processor.ts # Contextual truncation, structured parsers, settledValue helper
│   │   ├── security.ts         # Command filtering, rate limiting, audit logging with redaction
│   │   ├── sanitize.ts         # Shell injection prevention — validateShellArg/validateShellArgs/shellEscape
│   │   ├── chipset.ts          # Shared chipset family detection, modem path mapping, SIM config detection
│   │   ├── fetch-utils.ts      # Shared HTTP helpers with 5 MB streaming response size limit
│   │   ├── png-utils.ts        # Zero-dependency PNG decode/encode/draw primitives for screenshot annotation and diffing
│   │   ├── ui-dump.ts          # Shared uiautomator XML capture with concurrent-safe paths, on-device /data/local/tmp routing, and cleanup
│   │   ├── cleanup.ts          # Centralized process cleanup registry for SIGINT/SIGTERM/exit
│   │   ├── logger.ts           # stderr-safe logging (MCP-compliant)
│   │   ├── fs-utils.ts         # Filename sanitization, atomic write, private-dir helpers, within-dir containment check
│   │   ├── parse-utils.ts      # Shared parseIntSafe for env-var numeric parsing (single source of truth)
│   │   └── result-handle.ts    # Tempdir-backed tool result content cache with TTL, LRU, and token-hash isolation
│   └── config/
│       └── config.ts           # Configuration, env vars, startup validation
├── package.json
├── tsconfig.json
├── server.json                  # MCP Registry metadata (io.github.fullread/deepadb)
├── .gitignore
├── README.md
├── SECURITY.md                  # Threat model, security architecture, deployment hardening, vulnerability reporting
├── CHANGELOG.md                 # Version history from v0.1.0 to current
├── LICENSE                      # Apache 2.0 license
└── tests/
    ├── run-all.mjs              # Run all test suites sequentially with summary (tracks skipped counts)
    ├── test-hw.mjs              # Hardware core: health, identity, baseband, thermal, profiles, wireless firmware, crash analysis (34 tests)
    ├── test-shell-files.mjs     # Shell, filesystem, packages, diagnostics (24 tests)
    ├── test-ui-control.mjs      # UI hierarchy, screenshots, settings, input gestures, UI automation, device awareness, accessibility, screen lock/unlock, multi-touch (46 tests)
    ├── test-monitoring.mjs      # Logcat watchers, snapshots, OTA, regression, workflows (43 tests)
    ├── test-security.mjs        # Input sanitization, shell injection, AT command safety, QEMU shell escaping, heap-dump validation (116 on-device, 105 host)
    ├── test-lifecycle.mjs       # App lifecycle, file push/pull, input, port forwarding, screen recording, test sessions (24 tests)
    ├── test-analysis.mjs        # Thermal/snapshot/regression comparison, firmware diff, screenshot diff, test gen, RIL intercept, AT cross-validation, permission management (23 tests)
    ├── test-boundaries.mjs      # Zod bounds enforcement, input injection, error paths, sensitive data protection, wireless ADB coverage, multi-device basics, tunnel automation, device-free coverage boundaries (78 tests)
    ├── test-sensors.mjs         # HAL sensors, IIO power monitors, category filters, formatting, wake-up, rate display (30 tests)
    ├── test-files-extended.mjs  # File tool coverage — write, find, stat, checksum, mkdir, rm, move, copy, chmod, touch, fsinfo, chown, grep, replace; push safety; sed-escape regression (95 tests)
    ├── test-result-handles.mjs # Result handle store — listing, retrieval, drop, isolation, eviction (19 tests)
    ├── test-qemu.mjs            # QEMU/KVM setup, image management, VM status, guest connectivity errors (13 on-device tests)
    ├── test-qemu-boot.mjs       # QEMU Alpine VM boot with auto-fetch of kernel/initrd, KVM acceleration, topology detection, guest ADB connectivity (17 on-device tests)
    ├── test-supply-chain.mjs    # Supply-chain hardening checks for fetch and network paths (24 tests)
    ├── test-sanitize-fuzz.mjs   # Property-based fuzzing of shell sanitizers — shellQuote/shellEscape round-trip, validateShellArg rejection (19 tests)
    ├── test-transports.mjs      # Transport smoke — HTTP/SSE + WebSocket MCP round-trip, GraphQL health query (8 tests)
    └── lib/
        └── harness.mjs          # Shared test harness (stdio JSON-RPC transport, assertion primitives)

Tech Stack

• Runtime: Node.js ≥22 (ES2024, ESM; Node 22.12+ for coverage)
• Language: TypeScript 6.0 (strict mode, NodeNext module resolution)
• MCP SDK: `@modelcontextprotocol/sdk` ^1.24.0 (currently resolves to 1.30.0)
• Validation: Zod ^4.4.3
• Transport: stdio (JSON-RPC), HTTP/SSE, WebSocket (optional `ws`), GraphQL API (optional `graphql`)

License

Apache License 2.0 — see LICENSE and NOTICE. The v1.1.2 release migrated from MIT to Apache 2.0 for the explicit patent grant and contributor attribution requirements; existing forks/installs remain valid under the prior MIT terms.