DeepADB
The deepest Android Debug Bridge MCP server β 147 tools from UI to baseband.
Ask AI about DeepADB
Powered by Claude Β· Grounded in docs
I know everything about DeepADB. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
DeepADB
MCP (Model Context Protocol) server providing full Android Debug Bridge (ADB) integration for AI agents. Enables MCP clients to directly interact with connected Android devices β inspecting state, running commands, managing apps, capturing logs, controlling device settings, analyzing UI hierarchies, recording screens, managing emulators, running structured test sessions, orchestrating multi-device operations, capturing network traffic, running CI pipelines, auditing accessibility, detecting performance regressions, executing cloud device farm tests, debugging over WiFi, building projects, and managing community plugins.
198 tools, 4 resources, and 4 prompts across 44 modules β the most comprehensive ADB MCP server available, with triple transport (stdio + HTTP/SSE + WebSocket), optional GraphQL API, defense-in-depth security, modem firmware analysis, workflow marketplace, AT command interface with multi-chipset support, RIL message interception, device profiling, baseband/modem integration, automated test generation, OTA update monitoring, SELinux auditing, thermal/power profiling, network device discovery, visual regression detection, workflow orchestration, accessibility auditing, and contextual truncation.
Architecture
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client β
β (Claude Code / claude.ai) β
ββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββ
β stdio (JSON-RPC) or HTTP/SSE or WebSocket
ββββββββββββββββββββββββΌββββββββββββββββββββββββββββ
β DeepADB Server β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββ β
β β Tool Modules (44) β β
β β 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 β β
β βββββββββββββββββββββββββββββββββββββββββββββββ€ β
β β Resources (4) β 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. All 198 tools work through the ADB bridge with automatic retry on transient failures.
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. All 198 tools work identically, with significantly lower latency.
Validated on hardware (Pixel 6a, Android 16, Termux + Magisk + QEMU 10.2.1) across a four-cell test matrix, 0 failures in any cell:
- ADB mode, no PIN: 383 passed / 10 skipped (393 total). Skips: 5 QEMU (on-device only), 1 shell round-trip (requires /bin/sh on host, skipped on Windows), 4 screen-state (require DA_TEST_PIN).
- ADB mode, with PIN: 387 passed / 6 skipped. The 4 screen-state tests unlock.
- On-device mode, no PIN: 419 passed / 4 skipped (423 total). All QEMU tests unlock including Alpine Linux VM boot with KVM acceleration, big.LITTLE CPU topology detection, guest ADB connectivity error handling, and clean VM shutdown. Skips: 4 screen-state (require PIN).
- On-device mode, with PIN: 420 passed / 3 skipped. Every test enabled by the environment runs; the 3 skips are setup-phase steps that no-op when Alpine kernel/initrd/disk are already cached.
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 throughsu -cto 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 idprobe 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 <deepadb-repo> && 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
Quick Start
npm install
npm run build
npm run inspector # Test with MCP Inspector
npm start # Run directly (stdio mode)
# HTTP/SSE mode for browser-based clients
DA_HTTP_PORT=3000 npm start
# WebSocket mode (requires: npm install ws)
DA_WS_PORT=3001 npm start
# GraphQL API (requires: npm install graphql) β runs alongside any transport
DA_GRAPHQL_PORT=4000 npm start
Claude Code Configuration
{
"mcpServers": {
"deepadb": {
"command": "node",
"args": ["/path/to/DeepADB/build/index.js"]
}
}
}
Available Tools (198)
Health (1 tool)
adb_health_checkβ Comprehensive toolchain validation: ADB binary, server, device connection, authorization, root access, and storage writability
Device (3 tools)
adb_devicesβ List all connected devices with state, model, and product infoadb_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 optionsadb_uninstallβ Remove package with optional data retentionadb_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 cacheadb_grant_permissionβ Grant a runtime permission to a packageadb_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/deniedadb_force_stopβ Force-stop an app immediatelyadb_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
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 filesystemadb_lsβ List device directory contents (simple or detailed)adb_catβ Read text file from device with optional line limitadb_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 cappingadb_file_statβ File metadata: size, permissions, timestamps, ownership, SELinux contextadb_file_checksumβ SHA-256/SHA-1/MD5 hash with size-based timeout estimationadb_mkdirβ Create directories with parent creation (-p), hard-blocked kernel pathsadb_rmβ Delete files/directories with depth-based recursive protection and symlink resolutionadb_file_moveβ Move/rename with source depth protection and post-verifyadb_file_copyβ Copy with pre-flight size+space check and post-verify size matchadb_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, limitationsadb_file_chownβ Change ownership (root required, depth-based recursive protection)adb_grepβ Search file contents with fixed-string default, recursive depth control, result cappingadb_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 selectionadb_logcat_clearβ Clear all logcat buffersadb_logcat_crashβ Crash buffer log snapshot
Logs β Persistent Watchers (4 tools)
adb_logcat_startβ Start a background logcat watcher with ring buffer accumulationadb_logcat_pollβ Retrieve new lines since last poll from a running watcheradb_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 infoadb_networkβ WiFi, cellular, and IP connectivity (parallel query)adb_topβ CPU and memory usage snapshotadb_perf_snapshotβ Parallel memory, frame stats, and CPU profiling for a packageadb_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
UI (10 tools)
adb_screencapβ Take screenshot with filename sanitization, saves locallyadb_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 numberadb_current_activityβ Get focused activity and top window stackadb_inputβ Send tap, swipe, text, or keyevent inputadb_start_activityβ Launch activities by intent or component nameadb_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 callsadb_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 verificationadb_airplane_cycleβ Cycle airplane mode on/off to force cellular re-registrationadb_wifiβ Enable or disable WiFiadb_mobile_dataβ Enable or disable mobile dataadb_locationβ Set location mode (off/sensors/battery/high)adb_screenβ Wake, sleep, toggle, lock, or unlock the screen. Lock verifies keyguard state viadumpsys window. Unlock useswm dismiss-keyguard(works for swipe keyguards); supplypinto perform the full PIN entry sequence: wakes screen, swipes up to reveal keypad, types PIN, confirms, and verifies the keyguard sleep token was releasedadb_settings_getβ Read any Android setting from system/secure/global namespaceadb_settings_putβ Write any Android setting with read-back verificationadb_rebootβ Reboot device (normal, recovery, or bootloader mode)
Wireless Debugging (4 tools)
adb_pairβ Pair with device over WiFi using pairing codeadb_connectβ Connect to device over WiFi/TCPadb_disconnectβ Disconnect wireless device(s)adb_tcpipβ Switch USB device to TCP/IP mode (auto-detects device IP)
Port Forwarding (5 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 mappingsadb_forward_removeβ Remove a port forward or all forwardsadb_reverse_removeβ Remove a reverse forward or all reverse forwards
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 pkgadb_qemu_imagesβ Manage VM disk images: list, create (qcow2/raw), delete. Path containment verification prevents traversaladb_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 forwardingadb_qemu_stopβ Stop a running VM (graceful SIGTERM or force SIGKILL). Auto-disconnects guest ADB before killing. Reports running VMs if no name givenadb_qemu_statusβ Full status: KVM/QEMU availability, host resource budget, running VMs with PID/resources/uptime/ports/ADB connection state, image inventoryadb_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 VMsadb_qemu_disconnectβ Disconnect from a guest VM's ADB service. Clears connection state and removes guest from device listadb_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 directoryadb_test_stepβ Capture a numbered step with screenshot and logcat into the sessionadb_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 simultaneouslyadb_multi_compareβ Run a command on all devices and highlight output differencesadb_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
Input Gestures & UI Automation (15 tools)
adb_input_dragβ Drag from point A to point B (usesdraganddropwith 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 durationadb_input_double_tapβ Double tap with configurable interval between tapsadb_input_textβ Dedicated text input with space/special character handlingadb_open_urlβ Open a URL on the device via VIEW intentadb_orientationβ Get or set screen orientation (auto/portrait/landscape/reverse)adb_clipboardβ Read or write device clipboardadb_input_pinchβ Multi-touch pinch (zoom out) or spread (zoom in) gesture. Two fingers move symmetrically around a center point. Layered injection: parallelinput swipe(universal, no root) or rawsendeventMT Type B protocol (true multi-touch, root required). Auto-detects touchscreen device and capabilities viagetevent -p. Configurable center, radius, duration, angle, and interpolation stepsadb_tap_elementβ Find element by text/resource-id/content-description and tap its centeradb_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-tapadb_screenshot_compressedβ Capture screenshot with size/quality metadata for token-efficient workflowsadb_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 calladb_device_stateβ Combined snapshot: battery level/status/temp, network type, WiFi state, screen on/off, orientation, foreground activityadb_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 JSONadb_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 analysisadb_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 timeoutadb_ci_device_readyβ Structured pass/fail readiness check (boot, PM, screen, network, disk)adb_ci_run_testsβ Run instrumented tests viaam instrumentwith 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 analysisadb_signal_detailβ RSRP, RSRQ, SINR, RSSI, timing advance β raw radio measurements for signal analysisadb_neighboring_cellsβ All visible LTE/5G/WCDMA/GSM cells with identities and signal strengthsadb_carrier_configβ Carrier configuration dump, carrier ID, preferred APNadb_modem_logsβ RIL radio buffer, telephony framework, RILJ/RILC, kernel dmesg (root) modem logs
Accessibility Auditing (3 tools)
adb_a11y_auditβ Automated WCAG audit: missing labels, undersized touch targets (<48dp), duplicate descriptions, unfocusable clickablesadb_a11y_touch_targetsβ List all interactive elements with touch target dimensions in dp, flag undersizedadb_a11y_treeβ Accessibility-focused UI tree showing only screen-reader-relevant elements with roles, labels, and states
Regression Detection (3 tools)
adb_regression_baselineβ Capture performance baseline (memory, CPU, frame stats, battery, network) to JSONadb_regression_checkβ Compare current performance against a saved baseline with configurable regression thresholdsadb_regression_historyβ List all saved baselines with trends, optionally filtered by package
Device Farm (3 tools)
adb_farm_runβ Run instrumented tests on Firebase Test Lab across multiple device models and API levelsadb_farm_resultsβ Retrieve results from a Test Lab run or list recent test matricesadb_farm_matrixβ List available device models and Android versions on Firebase Test Lab
Plugin Registry (3 tools)
adb_registry_searchβ Search the community plugin registry, shows install status and available updatesadb_registry_installβ Download and install a plugin from the registry by nameadb_registry_installedβ List locally installed plugins with version and update availability
Plugins (2 tools)
adb_plugin_listβ List all loaded plugins with paths and load timesadb_plugin_infoβ Plugin system documentation and example plugin format
Build (2 tools)
adb_gradleβ Run any Gradle task in a project directoryadb_build_and_installβ Build debug APK and install via ANDROID_SERIAL targeting
AT Commands (5 tools)
adb_at_detectβ Auto-detect modem AT command device node by chipset family (Shannon, Qualcomm, MediaTek, Unisoc, generic). Probes known paths and returns the first responding nodeadb_at_sendβ Send a single AT command to the modem with response capture. Auto-detects port or accepts manual override. Dangerous command blocklist with force overrideadb_at_batchβ Send multiple AT commands sequentially with per-command results. Configurable inter-command delayadb_at_probeβ Run a standard diagnostic probe: modem ID, signal quality, network registration, SIM status, operator, functionality modeadb_at_cross_validateβ Cross-validate baseband firmware by comparing AT command responses (ATI, AT+CGMR, AT+CGMM) against system properties. Flags discrepancies as potential firmware tampering, incomplete OTA, or property spoofing. Shannon-specific AT+DEVCONINFO support. Requires root
Screenshot Diffing (3 tools)
adb_screenshot_baselineβ Capture and save a named screenshot baseline with metadata (dimensions, SHA-256, timestamp)adb_screenshot_diffβ Compare current screen against a saved baseline using pixel-level PNG decoding. Reports changed pixel count/percentage, bounding box of changed region, and supports a tolerance threshold for absorbing dynamic elements like clocksadb_screenshot_historyβ List all saved screenshot baselines with metadata
Workflow Orchestration (3 tools)
adb_workflow_runβ Execute a JSON-defined workflow: sequential device operations with variable substitution, conditional steps, loops, and result capture. Actions: shell, root_shell, install, screenshot, logcat, getprop, sleepadb_workflow_validateβ Validate workflow structure without executing. Shows execution planadb_workflow_listβ List saved workflow files in the workflows directory
Split APK Management (4 tools)
adb_install_bundleβ Install split APKs (app bundles) viainstall-multiplewith replace and downgrade optionsadb_list_splitsβ Show all APK split paths for a package with classification (base, config.density, config.language, etc.) and total sizeadb_extract_apksβ Pull all splits for a package to a local directory for analysis or backupadb_apex_listβ List installed APEX modules with version info
Device Mirroring (3 tools)
adb_mirror_startβ Start live screen mirroring via scrcpy. Supports windowed and headless modes, recording, bitrate/FPS/resolution control, stay-awake, and screen-offadb_mirror_stopβ Stop mirroring for a device or all devicesadb_mirror_statusβ Check scrcpy availability and list active mirroring sessions
Automated Test Generation (3 tools)
adb_test_gen_from_uiβ Analyze the current screen's interactive elements and generate a workflow that taps each one, screenshots, and checks for crashesadb_test_gen_from_intentsβ Analyze a package's registered activities and generate a workflow that launches each exported activity with crash detectionadb_test_gen_saveβ Save a generated workflow JSON to the workflows directory for later execution
OTA Update Monitoring (3 tools)
adb_ota_fingerprintβ Capture system fingerprint: build ID, Android version, security patch, bootloader, baseband firmware, kernel, A/B slotadb_ota_checkβ Compare current system state against a saved fingerprint to detect OTA updates. Identifies changed fields and recommends re-baseliningadb_ota_historyβ List all saved fingerprints for a device with version progression over time
RIL Message Interception (3 tools)
adb_ril_startβ Start capturing RIL messages from the radio logcat buffer. Categorizes registration, cell info, signal, network, security, handover, and NAS eventsadb_ril_pollβ Retrieve captured RIL messages with optional category filtering. Shows category distributionadb_ril_stopβ Stop a RIL capture session with category summary
Device Profiles (3 tools)
adb_profile_detectβ Auto-detect and build a device profile: hardware ID, chipset family, modem nodes, root status, 5G support, dual SIM configuration. Matches against built-in library for known quirksadb_profile_saveβ Save a device profile to the profiles libraryadb_profile_listβ List built-in and user-saved device profiles
Modem Firmware Analysis (3 tools)
adb_firmware_probeβ Comprehensive firmware identification: parses baseband (Shannon/Qualcomm/MediaTek/Unisoc/HiSilicon/Intel), bootloader, and RIL implementation into structured components. Reports kernel, security patch, A/B slot, verified boot state, VBMeta, hypervisor, and OTA partition inventoryadb_firmware_diffβ Compare all firmware components (baseband, bootloader, kernel, security patch, build ID, Android version, RIL) between saved fingerprints or live device. Deep parsed diffs for baseband and bootloader when changes detectedadb_firmware_historyβ Track firmware progression across all saved OTA fingerprints with multi-component change detection (baseband, bootloader, kernel, security patch, build ID, Android version) and parsed baseband diffs
Wireless Firmware (4 tools)
adb_wifi_firmwareβ WiFi chipset and firmware identification: driver version, firmware version, supported bands (2.4/5/6 GHz), WiFi standard detection (5/6/6E/7), current connection info. MAC address opt-in onlyadb_bluetooth_firmwareβ Bluetooth firmware and chipset identification: firmware version, BT version (4.0β5.4 from LMP), adapter state, LE capabilities (2M PHY, Coded PHY, extended advertising), active profiles (A2DP/HFP/HID/LE Audio), bonded device count. MAC/name opt-in onlyadb_nfc_firmwareβ NFC controller firmware: controller type (NXP/Broadcom/Samsung/ST), firmware version, supported technologies (NFC-A/B/F/V, MIFARE), secure element (eSE/UICC), HCE supportadb_gps_firmwareβ GNSS/GPS chipset and firmware identification: hardware model (manufacturer, chip, firmware), supported constellations (GPS/GLONASS/Galileo/BeiDou/QZSS/NavIC/SBAS), signal types with frequencies, dual-frequency (L1+L5) detection, raw GNSS measurement capabilities, A-GPS modes (MSB/MSA), SUPL server configuration, carrier phase measurements
Workflow Marketplace (3 tools)
adb_market_searchβ Search the workflow marketplace for community-shared workflow definitions with keyword and tag filtering. Shows install statusadb_market_installβ Download, validate (JSON structure + SHA-256 integrity), and install a marketplace workflow for immediate use with adb_workflow_runadb_market_exportβ Package a local workflow with marketplace metadata (author, version, tags, SHA-256) and generate a registry manifest entry for sharing
SELinux & Permission Auditing (3 tools)
adb_selinux_statusβ SELinux enforcement mode, policy version, shell context, recent AVC denial count. Root provides kernel dmesg denial statsadb_selinux_denialsβ List recent AVC denial messages with parsed source/target contexts, permission classes, and denied operations. Supports process filteringadb_permission_auditβ Audit runtime permission grants for a package grouped by dangerous permission category (Camera, Location, Phone, SMS, etc.). Flags high-sensitivity grants
Thermal & Power Profiling (3 tools)
adb_thermal_snapshotβ Capture all thermal zone temperatures, per-CPU frequencies/governors, cooling device states, battery temperature/current/voltage/power draw. Optional save as JSON baselineadb_thermal_compareβ Compare current thermal state against a saved baseline with per-zone temperature deltas and battery current changesadb_battery_drainβ Measure battery drain rate over a configurable duration (3-60s). Reports average mA, mW, estimated %/hour. Optional package-specific batterystats
Network Discovery (3 tools)
adb_network_scanβ Scan the local network for ADB-enabled devices via ARP table and optional IP range sweep. Probes ports 5555-5558 with batched parallel TCP probesadb_network_device_ipβ Get the WiFi IP of a connected device via multiple methods. Shows ADB TCP status and wireless connection instructionsadb_network_auto_connectβ One-step discover + connect: scans for ADB devices and automatically runs adb connect on each found listener
Hardware Sensor Access (2 tools)
adb_sensor_readβ Read current hardware sensor values via dumpsys sensorservice. Enumerates all sensors with vendor, type, mode, rate range, and wake capability. Returns last-known readings with timestamps and axis-labeled formatting. Category filter (13 categories) and listOnly discovery mode. No root requiredadb_iio_readβ Read raw hardware data from the Linux IIO subsystem. Auto-discovers IIO devices, classifies by kernel driver. On Tensor/Exynos: exposes per-rail ODPM power monitors showing real-time power consumption per SoC subsystem. Generic IIO path handles raw channels with calibrated scale+offset. Root required
MCP Resources (4)
Read-only device state surfaces accessible by MCP clients:
device://listβ List of all connected devices with state and model infodevice://info/{serial}β Device properties (model, OS, build, ABI)device://battery/{serial}β Parsed battery status (level, charging, temperature, voltage)device://telephony/{serial}β Telephony registry state for cellular analysis
MCP Prompts (4)
Pre-built workflow templates for common multi-step debugging tasks:
debug-crashβ Clear logcat β restart app β wait for reproduction β capture crash buffer β analyzedeploy-and-testβ Build β install β clear logcat β start watcher β launch β screenshot β reporttelephony-snapshotβ Capture telephony state, SIM/network operator, network type β summarize anomaliesairplane-cycle-testβ Start watcher β baseline telephony β cycle airplane mode β compare pre/post state
Key Features
Device Caching
Device discovery results are cached with a configurable TTL (default 5s), eliminating redundant adb devices subprocess calls during rapid tool sequences. Cache auto-invalidates on connection errors and after wireless connect/disconnect/pair operations.
Transient Failure Retry
The ADB bridge automatically retries on transient failures (device offline, connection reset, protocol fault) with configurable retry count and exponential backoff. Diagnostic commands skip retries to surface real issues immediately.
Output Protection
All ADB output passes through the OutputProcessor which normalizes line endings, enforces configurable character limits, and provides contextual truncation at logical boundaries (line breaks, section separators) rather than cutting mid-line. Includes structured parsers for battery, meminfo, and getprop output.
Persistent Logcat Streaming
Background logcat watchers run as spawned processes with ring buffer accumulation. Each poll returns only new lines since the last read. Supports multiple concurrent sessions (up to 10) with independent filters. Process cleanup handlers prevent orphaned adb logcat processes on server exit.
UI Hierarchy Analysis
Full view tree capture via uiautomator dump with parsed XML extraction. Returns structured element data including text, resource-id, content-description, class names, bounds coordinates with tap-ready center points, and interaction flags. Pre-compiled regex attribute extraction for efficient parsing.
Security Middleware
Multi-layered security activated via DA_SECURITY=true. Provides command blocklist/allowlist filtering, rate limiting (commands per minute), and audit logging with automatic credential redaction. Security checks are integrated into adb_shell, adb_root_shell, adb_multi_shell, adb_multi_compare, adb_input, adb_batch_actions, and adb_start_activity. Configurable via environment variables for different deployment scenarios.
Input Sanitization
All tools that interpolate user-supplied parameters into shell command strings validate inputs against shell metacharacters before execution. Package names, property keys, service names, setting keys, test identifiers, network interface names, and tcpdump filters are all validated through a centralized validateShellArg() function that rejects ;, |, &, $, backticks, parentheses, and other injection vectors. File paths use single-quoted shell escaping to prevent $() command substitution. The adb_input tool applies type-specific validation: tap/swipe accept only numeric coordinates, keyevent accepts only alphanumeric keycodes, and text is shell-escaped for literal delivery. The adb_batch_actions tool enforces the same per-action-type validation (digits-only for coordinates, alphanumeric for keycodes, shell-escape for text) and routes every assembled command through the security middleware. Deserialized JSON from snapshot files is validated before shell interpolation. Every z.number() parameter across all 198 tools has explicit .min()/.max() Zod bounds to prevent resource exhaustion from extreme values. The LocalBridge has explicit handlers for every ADB subcommand used by tool modules, preventing unquoted fallthrough to the default shell handler. In on-device mode, privilege escalation uses a frozen 16-command allowlist and restricted-path regex β the elevation set is ReadonlySet + Object.freeze, not configurable at runtime. The HTTP/SSE transport denies cross-origin requests by default (configurable via DA_HTTP_CORS_ORIGIN), the plugin registry verifies SHA-256 integrity hashes and prevents path traversal via directory containment checks, and the workflow engine enforces step count (200), sleep duration (5 min), and repeat iteration (100) limits. Fetch helpers enforce a 5 MB response body limit. Getprop output parsing handles Windows \r\n line endings via .trim() before regex matching, and dual SIM slot counts are capped at 4 to prevent resource exhaustion from corrupted device properties.
Multi-Device Orchestration
Run commands, install APKs, and compare outputs across multiple connected devices in parallel. Essential for comparative testing across Android versions and device models.
Snapshot/Restore
Capture comprehensive device state snapshots (packages, settings across all namespaces, system properties) to JSON files. Compare current state against saved snapshots to detect drift. Restore settings from snapshots for reproducible test environments.
Network Traffic Capture
On-device packet capture via tcpdump with pcap file pull for Wireshark analysis. Includes active connection listing via ss/netstat with /proc/net fallback for devices without those tools.
CI/CD Integration
Purpose-built tools for automated pipelines: wait for device boot with polling, structured readiness checks, and instrumented test execution with parsed pass/fail results.
Plugin Architecture
Dynamic tool module loading from a configurable plugins directory. Plugins are standard JavaScript ESM modules that export a register(ctx) function receiving the full ToolContext. Loaded at server startup, enabling community contributions without modifying core code.
Community Plugin Registry
Search, install, and manage plugins from a configurable registry URL. Shows install status, version comparison, and available updates. Downloads plugin files with companion metadata into the plugins directory for loading on next restart. Security features include SHA-256 integrity verification (when provided by the registry manifest), path traversal protection, and register() export sanity checking.
Baseband/Modem Integration
Deep cellular radio inspection tools for advanced Android development and research. Extracts modem firmware identification, cell identity parameters (CID, TAC, EARFCN, PCI), raw signal measurements (RSRP, RSRQ, SINR), neighboring cell surveys, carrier configuration, and multi-source modem logs (RIL radio buffer, telephony framework, kernel dmesg). Supports Shannon/Exynos, Qualcomm, MediaTek, and Unisoc chipset families via standard Android telephony APIs. Includes Google Tensor SoC detection (gs101/gs201/zuma/zumapro) for automatic Shannon modem path routing on Pixel 6β9 devices. Dual SIM detection reports per-slot SIM state, operator, network type, and country for DSDS, DSDA, and TSTS configurations.
Accessibility Auditing
Automated WCAG accessibility checks on the live UI hierarchy. Detects missing labels on interactive elements, undersized touch targets below the 48dp guideline (density-aware), images without content-descriptions, clickable elements missing focusability, and duplicate content-descriptions. Generates structured reports with severity levels. Includes a dedicated accessibility tree view for screen reader debugging.
Regression Detection
Capture performance baselines (memory, CPU, frame stats, battery, network state) and compare subsequent runs against them. Configurable regression thresholds for memory (+20%), CPU (+50%), and jank rate (+25%). Maintains a history of baselines for trend analysis across releases.
Device Farm Integration
Cloud-based test execution via Firebase Test Lab through the gcloud CLI. Run instrumented tests across multiple device models and API levels, retrieve structured results, and list available test matrix configurations. Graceful fallback with setup instructions if gcloud is unavailable.
HTTP/SSE Transport
Alternative to stdio for browser-based MCP clients. Set DA_HTTP_PORT to start an HTTP server with SSE streaming. Provides /sse (client subscription), /message (JSON-RPC), and /health endpoints. Cross-origin requests are denied by default β set DA_HTTP_CORS_ORIGIN to explicitly allow a specific origin.
Test Session Management
Structured test workflows with numbered steps. Each step captures a screenshot and logcat snapshot into an organized directory with a Markdown manifest. Designed for reproducible test documentation.
AT Command Interface
Direct AT command passthrough to the modem via root access, enabling raw interrogation beyond the Android telephony framework. Multi-chipset support auto-detects device nodes for Samsung Shannon/Exynos, Qualcomm Snapdragon, MediaTek, Unisoc/Spreadtrum, and generic USB modems. Input validation rejects shell metacharacters from both AT command strings and device node paths before root shell interpolation. A safety blocklist prevents accidental execution of dangerous commands (AT+CFUN=0, AT+EGMR, etc.) with an explicit force override.
Screenshot Diffing
True pixel-level visual regression detection. Captures named screenshot baselines and compares the current screen state by decoding PNG pixel data (IHDR parsing, IDAT decompression, all 5 PNG filter types) and comparing actual RGB values. Reports changed pixel count and percentage, bounding box of the changed region with vertical screen position, and dimension/size deltas. Supports a tolerancePercent parameter (0β100) that absorbs minor dynamic changes like clock displays or notification badges β a 1% tolerance reliably absorbs nav bar clock changes (~0.5% of pixels) while catching any real UI regression. SHA-256 fast-path for exact matches. Zero external dependencies.
Workflow Orchestration
Declarative JSON workflow engine for repeatable multi-step device operations. Supports variable substitution ({{pkg}}), conditional steps (if expressions with ==, !=, contains), loops (repeat, capped at 100 iterations), and result capture into variables for downstream steps. Actions map directly to ADB bridge operations with full security middleware enforcement. Workflow validation enforces a 200-step maximum and 5-minute sleep cap per step to prevent resource exhaustion from malicious or malformed workflow definitions.
Split APK Management
Support for modern Android delivery formats. Install app bundles via install-multiple, inspect split APK structure (base + config splits for language, density, ABI), extract all splits locally for analysis, and list APEX modules.
Device Mirroring
Live screen mirroring via scrcpy integration. Supports windowed mode for visual feedback and headless mode for recording-only workflows. Per-device session tracking enables simultaneous mirroring of multiple connected devices. Process cleanup handlers prevent orphaned scrcpy processes.
Automated Test Generation
Analyzes live UI hierarchy and package intent registrations to auto-generate test workflow JSON compatible with the workflow orchestration engine. UI-based generation taps each interactive element, screenshots, and checks for crashes. Intent-based generation launches each exported activity with crash detection.
OTA Update Monitoring
Tracks comprehensive system fingerprint (build ID, Android version, security patch, bootloader, baseband firmware, kernel version, A/B partition slot) across sessions. Compares current state against saved fingerprints to detect OTA updates. Identifies exactly which fields changed and recommends re-baselining performance metrics and screenshots after updates.
RIL Message Interception
Persistent Radio Interface Layer message capture from the Android radio logcat buffer. Spawns a background process that accumulates and categorizes RIL messages into: registration, cell_info, signal, network, security, handover, data, radio_state, sms, and NAS events. Poll-based retrieval with category filtering. Useful for passive monitoring of baseband-framework communication for radio diagnostics and cellular network research. Session limit (5) and process cleanup handlers prevent resource exhaustion.
Device Profile Library
Device-specific knowledge base containing hardware identification, chipset family, known modem device nodes, AT command compatibility, root requirements, dual SIM slot count, and quirks. Auto-detects profiles from connected devices and matches against a built-in library of known devices. Saved profiles persist across sessions and improve auto-detection accuracy for tools like adb_at_detect. Community-extensible through saved profile files.
WebSocket Transport
Alternative to stdio and HTTP/SSE for MCP clients that benefit from true bidirectional streaming. Lower latency than SSE polling with better web framework compatibility. Requires the ws npm package as an optional peer dependency. Set DA_WS_PORT to enable.
Modem Firmware Analysis
Comprehensive multi-component firmware identification, diffing, and history tracking. Parses baseband version strings for 6 chipset families: Shannon/Exynos (including Google Pixel/Tensor g5123b-* format and classic Samsung S5123AP_CL* format), Qualcomm MPSS branch/version/build, MediaTek MOLY branch/release/milestone, Unisoc/Spreadtrum SoC model/version, HiSilicon/Kirin model/carrier code, and Intel XMM model/branch. Also parses bootloader versions (Pixel codename/version/build, Samsung model/carrier/revision) and RIL implementation strings (Samsung S.LSI vendor/id/API/build date, Qualcomm, MediaTek). The firmware probe reports 8 sections: baseband, bootloader, RIL, kernel, security/build, partition/boot (A/B slot, secure boot, verified boot, flash lock), VBMeta integrity, and OTA partition inventory. The diff tool compares all firmware components between saved fingerprints or live device state, with deep parsed sub-diffs for baseband and bootloader. The history tool tracks multi-component firmware progression across OTA fingerprints.
Workflow Marketplace
Community sharing layer for the workflow orchestration engine. Search a registry of community-contributed test workflows, diagnostic sequences, and audit procedures. Download and install workflows directly for immediate execution with adb_workflow_run. Export local workflows with marketplace metadata and auto-generated registry manifest entries for submission. SHA-256 integrity verification on download.
GraphQL API
Optional HTTP endpoint serving a GraphQL API for composed device queries. Enables clients to fetch device info, battery, network, and arbitrary properties in a single request instead of multiple MCP tool calls. POST body size limited to 1 MB. Device properties are pre-fetched once per resolution to minimize subprocess calls. Requires the graphql npm package as an optional peer dependency. Set DA_GRAPHQL_PORT to enable.
SELinux & Permission Auditing
Inspects SELinux enforcement mode, queries AVC denials from logcat and kernel audit logs, and audits runtime permission grants per package. Groups granted permissions by dangerous category (Camera, Location, Phone, SMS, etc.) and flags high-sensitivity grants like background location and manage-external-storage. Extends the security auditing surface to the OS permission layer.
Thermal & Power Profiling
Captures thermal zone temperatures from sysfs, per-CPU frequency scaling states and governors, cooling device activity, and battery drain rates. Complements regression detection with thermal/power baselines for issues that manifest as heat or battery drain rather than frame drops. Includes timed drain measurement with mA/mW/estimated-%per-hour calculations.
Network Device Discovery
Scans the local network for ADB-enabled devices via ARP table queries and optional IP range sweeps. Probes common ADB ports (5555-5558) with batched parallel TCP connection attempts. Extracts device WiFi IPs via multiple methods. Auto-connect mode discovers and connects to devices in one step. Streamlines wireless debugging workflows.
QEMU/KVM Virtualization
On-device virtual machine management using QEMU with KVM hardware acceleration. Enables running guest Android VMs directly on the physical device β a capability unique to DeepADB. Dynamic resource allocation auto-detects host CPU cores and physical RAM, reserving 1 core and 35% of memory for the host OS to prevent starvation. Multi-VM support tracks resource consumption across concurrent VMs, refusing new VMs when the pool is exhausted rather than degrading host performance. Disk image management with qcow2 (sparse, snapshot-capable) and raw formats. ADB port forwarding to guest VMs enables DeepADB's full tool suite to target both host and guest devices simultaneously. Process lifecycle tracked via the centralized cleanup registry with SIGTERM/SIGKILL shutdown. Path containment verification on all image operations prevents directory traversal.
ToolContext Architecture
All 44 tool modules receive a unified ToolContext dependency bundle containing server, bridge, deviceManager, logger, security, and config. Adding new cross-cutting dependencies requires no module signature changes.
Environment Variables
| Variable | Default | Description |
|---|---|---|
DA_LOCAL | Auto-detect | Force on-device mode (true/false). Auto-detects via /system/build.prop |
ADB_PATH | Auto-detect | Path to ADB binary (ignored in on-device mode) |
DA_TIMEOUT | 30000 | Default command timeout in milliseconds |
DA_MAX_OUTPUT | 50000 | Max output characters before truncation |
DA_MAX_LOGCAT | 500 | Max logcat lines per snapshot |
DA_DEVICE | (auto) | Default device serial (auto-selects if single device) |
DA_TEMP_DIR | OS temp | Temp directory for screenshots, pulled files, bug reports, test sessions, snapshots |
DA_CACHE_TTL | 5000 | Device list cache TTL in milliseconds (0 = disabled) |
DA_RETRY_COUNT | 1 | Number of retries for transient ADB failures |
DA_RETRY_DELAY | 500 | Base retry delay in ms (doubles each attempt) |
DA_LOG_LEVEL | info | Log level: debug, info, warn, error |
DA_SECURITY | false | Enable security middleware (command filtering, rate limiting) |
DA_BLOCKED_COMMANDS | (none) | Comma-separated list of blocked shell command substrings |
DA_ALLOWED_COMMANDS | (none) | Comma-separated allowlist (if set, only matching commands run) |
DA_RATE_LIMIT | 0 | Max commands per minute (0 = unlimited) |
DA_AUDIT_LOG | true | Log all executed commands for audit trail (set to false to disable) |
DA_PLUGIN_DIR | {tempDir}/plugins | Directory to scan for plugin .js modules at startup |
DA_REGISTRY_URL | GitHub default | URL of the community plugin registry JSON manifest |
DA_HTTP_PORT | (disabled) | Set to a port number to enable HTTP/SSE transport mode |
DA_HTTP_HOST | 127.0.0.1 | Bind address for HTTP/SSE, WebSocket, and GraphQL servers |
DA_AUTH_TOKEN | (none β open) | Bearer token for network transports. When set, all HTTP/SSE/WS/GraphQL requests require Authorization: Bearer <token> header. Health endpoints exempt. |
DA_HTTP_CORS_ORIGIN | (none β deny) | Allowed CORS origin for HTTP/SSE |
DA_WS_PORT | (disabled) | Set to a port number to enable WebSocket transport mode (requires npm install ws) |
DA_WS_CORS_ORIGIN | (none β deny) | Allowed CORS origin for WebSocket health endpoint |
DA_GRAPHQL_PORT | (disabled) | Set to a port number to enable the GraphQL API endpoint (requires npm install graphql) |
DA_GRAPHQL_CORS_ORIGIN | (none β deny) | Allowed CORS origin for GraphQL API |
DA_WORKFLOW_REGISTRY_URL | (derived from DA_REGISTRY_URL) | URL of the workflow marketplace JSON manifest |
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)
β β βββ 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)
β β βββ 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 (5 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, multi-chipset, cross-validation (5 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)
β β βββ sensors.ts # Hardware sensor enumeration, IIO power monitor reading (2 tools)
β β βββ wireless-firmware.ts # WiFi, Bluetooth, NFC, GPS firmware identification (4 tools)
β β βββ build.ts # Gradle build and install (2 tools)
β β βββ resources.ts # MCP Resources β device state surfaces (4 resources)
β β βββ 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)
β βββ 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 # MIT 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 (25 tests)
βββ test-security.mjs # Input sanitization, shell injection, AT command safety, QEMU shell escaping, heap-dump validation (46 tests)
βββ 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 (46 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-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)
βββ lib/
βββ harness.mjs # Shared test harness (stdio JSON-RPC transport, assertion primitives)
Tech Stack
- Runtime: Node.js β₯22 (ES2024, ESM)
- Language: TypeScript 6.0 (strict mode, NodeNext module resolution)
- MCP SDK:
@modelcontextprotocol/sdk^1.24.0 (currently resolves to 1.29.0) - Validation: Zod ^3.25.0
- Transport: stdio (JSON-RPC), HTTP/SSE, WebSocket (optional
ws), GraphQL API (optionalgraphql)
License
MIT
