{
  "markdown": "# droidsight\n\n[![CI](https://github.com/edgecasehuman/droidsight/actions/workflows/ci.yml/badge.svg)](https://github.com/edgecasehuman/droidsight/actions/workflows/ci.yml)\n[![Security audit](https://github.com/edgecasehuman/droidsight/actions/workflows/audit.yml/badge.svg)](https://github.com/edgecasehuman/droidsight/actions/workflows/audit.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![crates.io](https://img.shields.io/crates/v/droidsight.svg)](https://crates.io/crates/droidsight)\n[![npm](https://img.shields.io/npm/v/%40edgecasehuman%2Fdroidsight.svg)](https://www.npmjs.com/package/@edgecasehuman/droidsight)\n\nAn MCP server that drives a real Android device over ADB — and hands the agent\nback the screen its action produced.\n\nOne native binary. The server has no Python, Appium, scrcpy, or ffmpeg\ndependency and runs no Node at all — `npx` below is only a convenient\ninstaller — so the runtime is the binary plus `adb`. A background H.264\n`screenrecord` stream is decoded in process, so the screen that follows an\naction is attached to the tool result automatically instead of costing a second\nround trip to ask what happened.\n\nEvery image carries the coordinate space it was produced in, so a model can tap\nwhat it just looked at without guessing a scale factor. When the accessibility\ntree comes back empty — Flutter, React Native, canvas, games — OCR and template\nmatching still find the target.\n\nThis is a powerful local controller, not a sandbox. Run it only against a device\nand an MCP client you trust.\n\n## Install\n\n```bash\nnpx -y @edgecasehuman/droidsight\n```\n\nThat downloads a prebuilt binary for your platform and needs no build tools. The\nserver is also listed in the official [MCP Registry] as\n`io.github.edgecasehuman/droidsight`.\n\nTo compile it instead, from [crates.io]:\n\n```bash\ncargo install droidsight\n```\n\nOr from source:\n\n```bash\ncargo build --locked --release --bin droidsight\n```\n\n**Both compiling routes need NASM on the PATH.** The H.264 decoder is built from\nC++ by `openh264-sys2`, which assembles its hot paths with NASM, and no platform\nships it by default -- without it the build fails inside a transitive dependency\nrather than in this crate. Install it with `apt install nasm`,\n`brew install nasm`, or `winget install NASM.NASM`. The `npx` route above needs\nnone of this.\n\nThe server is `target/release/droidsight`. It speaks newline-delimited\nJSON-RPC 2.0 over stdin and stdout.\n\n[MCP Registry]: https://registry.modelcontextprotocol.io\n[crates.io]: https://crates.io/crates/droidsight\n\n### Client configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"android\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@edgecasehuman/droidsight\"],\n      \"env\": {\n        \"DROIDSIGHT_DEVICE_SERIAL\": \"<serial from `adb devices`>\"\n      }\n    }\n  }\n}\n```\n\nADB must be reachable through `PATH`, `ANDROID_SDK_ROOT`, `ANDROID_HOME`, or an\nexplicit `DROIDSIGHT_ADB_PATH`. If more than one authorized device is visible\nthe server refuses to guess; set `DROIDSIGHT_DEVICE_SERIAL`.\n\n## Tools\n\nThirty-one tools are published by default. Two more appear only when\n`DROIDSIGHT_ALLOW_SHELL=1` is set, and are listed last.\n\n### Seeing the screen\n\n| Tool | Purpose |\n|---|---|\n| `mcp_android_vision_query` | Screenshot, hierarchy, OCR, and element or template search. Its `elements` and `tap_element` actions avoid coordinate arithmetic entirely. |\n| `mcp_android_vision_stream` | Start, stop, or read the background H.264 stream. |\n| `mcp_android_get_view_hierarchy` | The accessibility tree as structured JSON. |\n| `mcp_android_smart_wait` | Block until an element appears, or time out. |\n\n### Driving the device\n\n| Tool | Purpose |\n|---|---|\n| `mcp_android_input_act` | Tap, type, key events, swipe, smart tap, and IME control. |\n| `mcp_android_tap_text` | Scan for text and tap it the instant it appears, retrying until timeout. Avoids the miss between a screenshot and a tap. |\n| `mcp_android_run_flow` | Run a bounded, fully prevalidated sequence of safe actions. |\n| `mcp_android_record_gesture` | Record raw touch input for a fixed duration. |\n| `mcp_android_play_gesture` | Replay a recorded gesture timeline. |\n\n### Applications\n\n| Tool | Purpose |\n|---|---|\n| `mcp_android_app_manage` | Launch, stop, list, install, and read crash logs. Uninstall, clear data, permission, enable, and disable additionally require `confirm_destructive`. |\n| `mcp_android_app_instrumentation` | Deep state inspection: activity, window, process list, stack traces. |\n| `mcp_android_open_url` | Open a URL. |\n| `mcp_android_start_intent` | Start an arbitrary intent. |\n\n### Device and system state\n\n| Tool | Purpose |\n|---|---|\n| `mcp_android_device_control` | Clipboard, battery, device info, lock state, unlock, rotation. |\n| `mcp_android_system_control` | Accessibility services and the draw-over-other-apps permission. **Grants screen-read and input-injection authority across every app.** |\n| `mcp_android_network_control` | Wi-Fi, mobile data, HTTP proxy, phone calls, SMS, wireless ADB pairing. |\n| `mcp_android_sensor_control` | Mock battery level and charging status; GPS mocking is emulator-only. |\n| `mcp_android_check_health` | Connectivity and responsiveness of the selected device. |\n| `mcp_android_check_debug_exposure` | Report which developer settings are enabled and therefore visible to apps. |\n\n### Diagnostics and data\n\n| Tool | Purpose |\n|---|---|\n| `mcp_android_diagnostic_stream` | Read logcat, clear it, or read buffered raw and semantic events. |\n| `mcp_android_read_recent_events` | Buffered device events from the optional monitor. |\n| `mcp_android_log_filter` | Filter logs by regex, tag, or priority. |\n| `mcp_android_get_notifications` | Dump posted notifications, including unredacted message content. |\n| `mcp_android_file_system` | List, read, push, and pull files, confined to `DROIDSIGHT_LOCAL_ROOT`. |\n| `mcp_android_forensics_control` | Query an on-device SQLite database, hash a file, or irreversibly delete an application's data. |\n\n### Capture and presence\n\n| Tool | Purpose |\n|---|---|\n| `mcp_android_start_recording` | Begin a screen recording, up to 180 seconds, written to the device. |\n| `mcp_android_stop_recording` | Stop it. The file stays on the device. |\n| `mcp_android_companion` | Post a notification, show a transient message, or open a URL for whoever is holding the phone. |\n| `mcp_android_sentinel_control` | Register a watched package. See [Background enforcement](#background-enforcement) before using it. |\n| `mcp_android_start_session`, `mcp_android_stop_session` | Session markers. They acknowledge the call and hold no server state. |\n\n### Only with `DROIDSIGHT_ALLOW_SHELL=1`\n\n| Tool | Purpose |\n|---|---|\n| `mcp_android_run_shell` | Run an arbitrary device shell command. No filtering of any kind. |\n| `mcp_android_run_macro` | Run up to 100 shell commands in sequence, stopping at the first failure. |\n\n## Coordinate space\n\nScreenshots are downscaled to 720 pixels wide by default, so a coordinate read\noff the returned pixels is usually **not** a device coordinate. Every tool that\nreturns an image also returns a `metadata.image` object describing how to\nconvert one:\n\n```json\n{\n  \"image\": {\n    \"width\": 720, \"height\": 1600,\n    \"device_width\": 1080, \"device_height\": 2400,\n    \"origin_x\": 0, \"origin_y\": 0,\n    \"scale\": 1.5,\n    \"coordinate_space\": \"image\",\n    \"note\": \"To convert a coordinate (x, y) read from this image into a device coordinate: device_x = 0 + x * 1.5, device_y = 0 + y * 1.5.\"\n  }\n}\n```\n\nWhen `coordinate_space` is `device`, the image is already 1:1 and coordinates\ncan be used directly. Request `max_width: 1440` to reduce or remove downscaling.\nCrops additionally report a non-zero `origin_x`/`origin_y` that must be added\nafter scaling.\n\nTaps, `uiautomator` hierarchy bounds, OCR boxes, and template matches are all in\ndevice coordinates. The background stream runs `screenrecord` without `--size`,\nso decoded frames are native resolution and share that one space.\n\nYou can avoid the arithmetic entirely. The `mcp_android_vision_query` tool's\n`elements` action returns an indexed snapshot with a precomputed center per\nelement, and its `tap_element` action takes that `snapshot_id` and an `index`.\n\n## Environment variables\n\n| Variable | Effect |\n|---|---|\n| `DROIDSIGHT_DEVICE_SERIAL` | The only Android target the process may use. Mandatory when ADB reports multiple authorized devices. |\n| `DROIDSIGHT_ADB_PATH` | Explicit path to the ADB executable. |\n| `DROIDSIGHT_LOCAL_ROOT` | Confines host paths used by APK installation and file push/pull. Defaults to the process working directory. |\n| `DROIDSIGHT_DEVICE_PIN` | Numeric PIN for UI actions that need automatic unlock. Supply at runtime only; never in source or a checked-in MCP configuration. |\n| `DROIDSIGHT_ALLOW_SHELL=1` | Publishes the arbitrary shell and macro tools. This grants authority equivalent to broad ADB shell access. Off by default. |\n| `DROIDSIGHT_DEBUG_LOG` | Path to a persistent debug log. Logging to a file is strictly opt-in; without this, warnings go to stderr and no file is written. |\n| `DROIDSIGHT_LOG` | Tracing filter. Defaults to `warn`, or `debug` when a debug log path is set. |\n| `DROIDSIGHT_EVENTS=1` | Starts the long-running device event monitor. Requires `DROIDSIGHT_DEVICE_SERIAL`. |\n| `DROIDSIGHT_SENTINEL=1` | Starts the background enforcement loop described under [Background enforcement](#background-enforcement). Off by default: it re-applies device state on a timer, including unlocking the screen. |\n\n## Continuous vision cache\n\nOne background H.264 `screenrecord` stream starts at process startup and the\nlatest decoded RGB frame is kept in memory. Screenshot tools and input\nobservations read that cache, so a snapshot is available immediately once the\nfirst frame decodes. A static screen's last frame stays valid while the stream\nruns; it does not expire merely because the encoder stopped emitting unchanged\npixels.\n\nThe stream allows 20 seconds for the first decodable frame before reconnecting.\nAfter that, silence is treated as a static screen, while EOF and read errors\nstill reconnect. Starting or stopping a stream synchronously clears its frame\ncache so a previous session's image cannot be reused. The\n`mcp_android_vision_stream` `stop` action suspends capture until an explicit\n`start`; shutdown drops the owned ADB stream and leaves no `screenrecord`\nprocess behind.\n\nContinuous capture has privacy, battery, CPU, and wireless-bandwidth costs. The\ndevice screen may contain sensitive information even though cached frames stay\nin process memory until a tool returns one. Use the explicit stop action when\ncapture should be suspended.\n\n## MCP transport\n\nStdout carries one JSON-RPC value per line; diagnostics go to stderr. The server\nsupports `initialize`, `tools/list`, and `tools/call`, plus the initialized\nnotification and legacy `mcp.*` aliases. Batch arrays are handled member by\nmember and produce one response-array line; notification-only batches produce no\noutput and empty batches are rejected. Clients must complete the ordered\n`initialize` request and `notifications/initialized` notification handshake\nbefore listing or calling tools; premature calls return JSON-RPC error `-32002`.\nInput frames are limited to 16 MiB; oversized or invalid UTF-8 frames are\nrejected without preventing the next valid request from being processed.\n\nPublished text from logs, events, notifications, device files, hierarchy and OCR\nresults, crash and forensic reports, instrumentation, shell/macro output, and\naggregate flows is limited to 256 KiB. Truncated responses carry\n`metadata.truncation` with the strategy, original size, returned size, and\nconfigured limit; chronological feeds retain their newest tail while\nfile-like output retains its head.\n\nFinite ADB subprocesses drain stdout and stderr concurrently and retain at most\n4 MiB from each stream while counting all observed bytes, which prevents pipe\ndeadlocks and unbounded capture. The optional event monitor owns its ADB child\nand reader thread and is cancelled, killed, joined, and reaped during transport\nshutdown rather than being left detached.\n\nOCR is an optional integration with an external Tesseract executable. Discovery\nprobes are limited to five seconds and recognition to 30 seconds; timed-out\nchildren are terminated and reaped before the tool returns an error.\n\nSmoke test:\n\n```bash\nprintf '%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\n  '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' \\\n  | cargo run --quiet --bin droidsight\n```\n\n## Destructive operations\n\nSome tools change device state irreversibly. `pm clear` deletes an\napplication's databases, preferences, accounts, and credentials, and it is\nreachable two ways. Both refuse to run without `\"confirm_destructive\": true`:\n\n- `mcp_android_forensics_control` with `\"action\": \"clear_app_data\"`, named for\n  what it does rather than for a cache eviction.\n- `mcp_android_app_manage` with `\"action\": \"clear_data\"`. The same tool gates\n  `uninstall`, `permission`, `enable`, and `disable` behind the same argument,\n  because each of them removes an application, its data, or a security control.\n\nThe guard is checked before any ADB command is issued, so a refused call does\nnot touch the device. It is a guardrail against an unintended call, not a\nsecurity boundary: a client that can invoke tools can also set the flag.\n\nThe gate covers unintended calls to those specific tools. It is not a\ncontainment boundary, and several operations of comparable impact are not behind\nit at all:\n\n- `mcp_android_system_control` enables an accessibility service, which grants\n  full screen-read and input-injection access across every app on the device,\n  and grants the draw-over-other-apps permission.\n- `mcp_android_network_control` sets a global HTTP proxy, forgets saved Wi-Fi\n  networks, and places real outbound phone calls.\n- `mcp_android_sensor_control` overrides sensor readings such as battery level\n  and status; its GPS location mocking uses the emulator console and applies\n  only to emulators, not physical devices.\n\n## Arbitrary shell access\n\n`DROIDSIGHT_ALLOW_SHELL=1` publishes two tools that pass command strings to the\ndevice shell verbatim: `mcp_android_run_shell`, and `mcp_android_run_macro` for\nbatches of up to 100 commands.\n\n**No command filtering of any kind is performed.** The environment variable is\nthe entire control. Once set, these tools are a strict superset of every gated\noperation above — `pm clear`, `pm uninstall`, and file deletion are all reachable\nwithout `confirm_destructive`, because the shell path never consults it. Leave\nthe variable unset unless the connected MCP client is as trusted as a local\nshell on the device.\n\n## Background enforcement\n\n`DROIDSIGHT_SENTINEL=1` starts a loop that wakes every five seconds and, for\neach watched package, re-applies the state it was told to hold: waking and\nunlocking the screen with a PIN supplied when the watch was registered, enabling\nan accessibility service, granting the overlay permission, and granting a list\nof runtime permissions. No watches exist until a client registers one, so an\nenabled sentinel with an empty watch list only ticks.\n\nTwo consequences are worth stating plainly:\n\n- **It reverses manual changes.** Revoking a permission or disabling the\n  accessibility service for a watched package is undone within five seconds.\n  Remove the watch first.\n- **It does not ask for `confirm_destructive`.** That gate covers an operator\n  calling `mcp_android_app_manage`; the loop invokes the same underlying\n  operation directly, because re-granting is the entire purpose of a watch.\n  Registering a watch is the consent step for everything that watch will\n  subsequently do on its own.\n\nThe loop performs no network I/O beyond the local ADB connection and contacts no\nremote service.\n\n## Build and test\n\nThe repository pins its Rust toolchain and keeps device-mutating scenarios out\nof the default test suite.\n\n```bash\ncargo fmt --all -- --check\ncargo clippy --locked --all-targets -- -D warnings\ncargo test --locked -- --test-threads=1\ncargo build --locked --release --bin droidsight\n```\n\nThese gates run on Linux, macOS, and Windows and pass without warning\nsuppressions. The compiler is pinned in `rust-toolchain.toml`; a separate CI job\ntype-checks the crate against Rust 1.89, the declared minimum.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) before changing device-affecting code.\n[SECURITY.md](SECURITY.md) documents private reporting, sensitive-evidence\nredaction, and the ADB, host, MCP, filesystem, logging, and shell trust\nboundaries. Participation is governed by\n[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).\n\n## Maturity\n\nThe host-only suite covers protocol parsing, schemas, serialization, ADB command\nconstruction, concurrent discovery, reconnect invalidation, device selection,\nsubprocess deadlines, JSON-RPC batches, path confinement, shell quoting, output\nbudgets, event-monitor teardown, hierarchy parsing, flow validation, stream\nframing and lifecycle, static-frame cache behavior, image encoding and\ncoordinate metadata, Samsung keyguard/window parsing, and intent failure\nhandling.\n\nThe release binary has been exercised over wireless debugging against a single\nSamsung device running Android 13, covering device state, battery, apps,\nhierarchy and element snapshots, OCR, screenshots and sequences, continuous\nH.264 capture, input and navigation, intents, logs, notifications, Wi-Fi\nscanning, file round trips, hashing, sessions, gesture capture, recording,\nrotation restoration, crash listing, and cleanup. Destructive application,\npermission, accessibility, overlay, telephony, network-mutation, GPS, and\nbattery-mocking operations are deliberately excluded from that matrix. Other\nvendors and Android releases still need their own qualification.\n\n## H.264 decoding\n\nThe vision cache decodes H.264 in process using [openh264], which builds Cisco's\nBSD-2-Clause C++ implementation from source. Cisco's royalty coverage applies to\nthe binaries Cisco itself publishes and does not transfer to a self-compiled\nbuild. If you redistribute binaries of this project, satisfying any applicable\nH.264 patent licensing is your responsibility.\n\n[openh264]: https://github.com/cisco/openh264\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 18406,
  "sha": "b7202576dabcb13cb3c5123864fd9ce916627f955ee4751e73bb2116d8719a8e",
  "repo_slug": "edgecasehuman/droidsight",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_edgecasehuman_droidsight_925e407a/readme"
}