droidsight

droidsight

一个 MCP 服务，通过 ADB 驱动真实的 Android 设备，并将操作后生成的屏幕画面交还给 Agent。

一个原生二进制文件。服务不依赖 Python、Appium、scrcpy 或 ffmpeg，也完全不运行 Node——下方的 npx 只是方便的安装方式——因此运行时只需该二进制文件和 adb。后台 H.264 screenrecord 流会在进程内解码，因此操作后的屏幕画面会自动附加到工具结果中，无需再多一次往返来询问发生了什么。

每张图像都会携带其生成时所处的坐标空间，因此模型可以点击刚刚看到的位置，无需猜测缩放系数。当无障碍树为空时——例如 Flutter、React Native、canvas 和游戏——OCR 和模板匹配仍然可以找到目标。

这是一个功能强大的本地控制器，不是沙箱。仅对你信任的设备和 MCP 客户端运行。

安装

npx -y @edgecasehuman/droidsight

这会下载适用于你平台的预构建二进制文件，无需构建工具。该服务也已列入官方 MCP Registry，名称为 io.github.edgecasehuman/droidsight。

若要自行编译，可从 crates.io 获取：

cargo install droidsight

也可以从源代码构建：

cargo build --locked --release --bin droidsight

两种编译方式都要求 PATH 中有 NASM。 H.264 解码器由 openh264-sys2 使用 C++ 构建，它会用 NASM 汇编其热点路径；各平台默认均不附带 NASM——若未安装，构建会在传递依赖内部失败，而不是在此 crate 中失败。可通过 apt install nasm、brew install nasm 或 winget install NASM.NASM 安装。上文的 npx 方式无需这些依赖。

服务位于 target/release/droidsight。它通过标准输入和标准输出使用以换行符分隔的 JSON-RPC 2.0。

客户端配置

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "@edgecasehuman/droidsight"],
      "env": {
        "DROIDSIGHT_DEVICE_SERIAL": "<serial from `adb devices`>"
      }
    }
  }
}

必须能通过 PATH、ANDROID_SDK_ROOT、ANDROID_HOME 或显式设置的 DROIDSIGHT_ADB_PATH 访问 ADB。如果检测到多个已授权设备，服务不会自行猜测；请设置 DROIDSIGHT_DEVICE_SERIAL。

工具

默认发布 31 个工具。设置 DROIDSIGHT_ALLOW_SHELL=1 后才会额外出现两个工具，并列在最后。

查看屏幕

工具	用途
mcp_android_vision_query	截屏、层级结构、OCR，以及元素或模板搜索。其 elements 和 tap_element 操作完全无需计算坐标。
mcp_android_vision_stream	启动、停止或读取后台 H.264 流。
mcp_android_get_view_hierarchy	以结构化 JSON 表示的无障碍树。
mcp_android_smart_wait	阻塞等待元素出现，或在超时后返回。

操控设备

工具	用途
mcp_android_input_act	点击、输入文本、按键事件、滑动、智能点击和 IME 控制。
mcp_android_tap_text	扫描文本并在其出现时立即点击；若未出现则重试，直至超时。避免截屏后再点击之间错过目标。
mcp_android_run_flow	运行有界且经过完整预验证的安全操作序列。
mcp_android_record_gesture	在固定时长内记录原始触控输入。
mcp_android_play_gesture	重放已记录的手势时间线。

应用

工具	用途
mcp_android_app_manage	启动、停止、列出和安装应用，并读取崩溃日志。卸载、清除数据、管理权限、启用和停用应用还需要 confirm_destructive。
mcp_android_app_instrumentation	深入检查状态：活动、窗口、进程列表和堆栈跟踪。
mcp_android_open_url	打开 URL。
mcp_android_start_intent	启动任意 intent。

设备和系统状态

工具	用途
mcp_android_device_control	剪贴板、电池、设备信息、锁定状态、解锁和旋转。
mcp_android_system_control	无障碍服务和“显示在其他应用上层”权限。可授予跨所有应用的屏幕读取和输入注入权限。
mcp_android_network_control	Wi-Fi、移动数据、HTTP 代理、电话、短信和无线 ADB 配对。
mcp_android_sensor_control	模拟电池电量和充电状态；GPS 模拟仅适用于模拟器。
mcp_android_check_health	检查所选设备的连接状态和响应情况。
mcp_android_check_debug_exposure	报告已启用、因此对应用可见的开发者设置。

诊断和数据

工具	用途
mcp_android_diagnostic_stream	读取或清除 logcat，或读取缓冲的原始事件和语义事件。
mcp_android_read_recent_events	从可选监控器读取缓冲的设备事件。
mcp_android_log_filter	按正则表达式、标签或优先级筛选日志。
mcp_android_get_notifications	转储已发布的通知，包括未脱敏的消息内容。
mcp_android_file_system	列出、读取、推送和拉取文件；操作范围限制在 DROIDSIGHT_LOCAL_ROOT 内。
mcp_android_forensics_control	查询设备上的 SQLite 数据库、计算文件哈希，或不可逆地删除应用数据。

录制和设备交互

工具	用途
mcp_android_start_recording	开始录屏，最长 180 秒，录制文件写入设备。
mcp_android_stop_recording	停止录屏。文件会保留在设备上。
mcp_android_companion	发布通知、显示临时消息，或为当前持有手机的人打开 URL。
mcp_android_sentinel_control	注册受监控的软件包。使用前请参阅后台强制执行。
mcp_android_start_session、mcp_android_stop_session	会话标记。它们会确认调用，但不保存任何服务端状态。

仅在 DROIDSIGHT_ALLOW_SHELL=1 时可用

工具	用途
mcp_android_run_shell	运行任意设备 shell 命令。不进行任何过滤。
mcp_android_run_macro	按顺序运行最多 100 条 shell 命令，遇到第一条失败命令时停止。

坐标空间

默认情况下，截图会缩小到宽 720 像素，因此根据返回图像读取的坐标 通常不是设备坐标。所有返回图像的工具也会返回一个 metadata.image 对象， 说明如何转换坐标：

{
  "image": {
    "width": 720, "height": 1600,
    "device_width": 1080, "device_height": 2400,
    "origin_x": 0, "origin_y": 0,
    "scale": 1.5,
    "coordinate_space": "image",
    "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."
  }
}

当 coordinate_space 为 device 时，图像已是 1:1，坐标可直接使用。请求 max_width: 1440 可减少或取消缩小。裁剪图像还会报告非零的 origin_x/origin_y，缩放后必须加上这些值。

点击坐标、uiautomator 层级结构边界、OCR 框和模板匹配结果均采用 设备坐标。后台流使用不带 --size 的 screenrecord，因此解码后的帧为原生分辨率， 并与上述坐标处于同一空间。

你也可以完全跳过计算。mcp_android_vision_query 工具的 elements 操作会返回带索引的快照，并为每个元素预先计算中心坐标；其 tap_element 操作则接收该 snapshot_id 和一个 index。

环境变量

变量	作用
DROIDSIGHT_DEVICE_SERIAL	进程唯一可使用的 Android 目标设备。ADB 报告有多个已授权设备时，此变量为必填项。
DROIDSIGHT_ADB_PATH	ADB 可执行文件的显式路径。
DROIDSIGHT_LOCAL_ROOT	限定 APK 安装和文件推送/拉取所用的主机路径。默认为进程工作目录。
DROIDSIGHT_DEVICE_PIN	用于需要自动解锁的 UI 操作的数字 PIN。仅在运行时提供；切勿写入源代码或签入 MCP 配置。
DROIDSIGHT_ALLOW_SHELL=1	发布任意 shell 和宏工具。这会授予相当于广泛 ADB shell 访问权限的能力。默认关闭。
DROIDSIGHT_DEBUG_LOG	持久化调试日志的路径。写入文件严格采用显式启用；未设置时，警告会输出到 stderr，且不会写入文件。
DROIDSIGHT_LOG	跟踪过滤器。默认为 warn；设置调试日志路径时默认为 debug。
DROIDSIGHT_EVENTS=1	启动长期运行的设备事件监视器。需要设置 DROIDSIGHT_DEVICE_SERIAL。
DROIDSIGHT_SENTINEL=1	启动后台强制执行中所述的后台强制执行循环。默认关闭：它会定时重新应用设备状态，包括解锁屏幕。

持续视觉缓存

进程启动时会启动一个后台 H.264 screenrecord 流，并将最新解码的 RGB 帧保存在内存中。屏幕截图工具和输入观察会读取该缓存，因此首帧解码后即可立即获取快照。流运行期间，静态屏幕的最后一帧仍然有效；编码器停止输出未发生变化的像素，不会导致该帧过期。

流会等待 20 秒以获取首个可解码帧，超时后便会重新连接。此后，无数据会被视为屏幕静止，而 EOF 和读取错误仍会触发重新连接。启动或停止流时会同步清除其帧缓存，避免重复使用上一个会话的图像。mcp_android_vision_stream 的 stop 操作会暂停捕获，直至显式执行 start；关闭时会释放所持有的 ADB 流，且不会留下 screenrecord 进程。

持续捕获会消耗隐私、电池、CPU 和无线带宽资源。即使缓存帧在工具返回前一直保存在进程内存中，设备屏幕上仍可能显示敏感信息。需要暂停捕获时，请使用显式停止操作。

MCP 传输

Stdout 每行承载一个 JSON-RPC 值；诊断信息写入 stderr。服务支持 initialize、tools/list 和 tools/call，以及 initialized 通知和旧版 mcp.* 别名。批处理数组会逐项处理，并输出一行响应数组；仅含通知的批处理不会产生输出，空批处理会被拒绝。客户端必须按顺序完成 initialize 请求和 notifications/initialized 通知握手，然后才能列出或调用工具；过早调用会返回 JSON-RPC 错误 -32002。输入帧限制为 16 MiB；超大或无效的 UTF-8 帧会被拒绝，但不会妨碍处理后续有效请求。

从日志、事件、通知、设备文件、层级结构和 OCR 结果、崩溃与取证报告、仪器检测、shell／宏输出以及聚合流中发布的文本，限制为 256 KiB。被截断的响应会携带 metadata.truncation，其中包含截断策略、原始大小、返回大小和配置的上限；按时间顺序排列的内容流会保留最新的尾部，而类似文件的输出会保留开头。

有限时长的 ADB 子进程会并发读取 stdout 和 stderr，每个流最多保留 4 MiB，同时统计所有已观察到的字节数，从而避免管道死锁和无界捕获。可选的事件监视器会管理自己的 ADB 子进程和读取线程；传输关闭时，会取消、终止、等待并回收它们，而不会将其留作分离进程。

OCR 是与外部 Tesseract 可执行文件集成的可选功能。发现探测最长耗时五秒，识别最长耗时 30 秒；超时的子进程会在工具返回错误前被终止并回收。

冒烟测试：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | cargo run --quiet --bin droidsight

破坏性操作

一些工具会不可逆地更改设备状态。pm clear 会删除应用的数据库、偏好设置、账号和凭据，可通过两种方式调用。两种方式都要求 "confirm_destructive": true，否则会拒绝执行：

• mcp_android_forensics_control 的 "action": "clear_app_data"，其名称直接描述了功能，而不是将其称为清除缓存。
• mcp_android_app_manage 的 "action": "clear_data"。同一工具也会要求为 uninstall、permission、enable 和 disable 提供相同参数，因为这些操作都会移除应用、应用数据或安全控制。

在发出任何 ADB 命令之前都会检查此防护条件，因此被拒绝的调用不会触及设备。这是为了防止意外调用而设的防护措施，不是安全边界：能够调用工具的客户端也能设置此标志。

该门控仅涵盖对这些特定工具的意外调用。它不是隔离边界，且有几种影响程度相当的操作完全不受其限制：

• mcp_android_system_control 会启用一项无障碍服务，使其获得对设备上所有应用的完整屏幕读取和输入注入权限，并授予在其他应用上层显示的权限。
• mcp_android_network_control 会设置全局 HTTP 代理、忘记已保存的 Wi-Fi 网络，并拨打真实的外呼电话。
• mcp_android_sensor_control 会覆盖电池电量和状态等传感器读数；其 GPS 位置模拟使用模拟器控制台，仅适用于模拟器，不适用于实体设备。

任意 shell 访问

DROIDSIGHT_ALLOW_SHELL=1 会发布两个将命令字符串原样传递给设备 shell 的工具：mcp_android_run_shell，以及用于批量执行最多 100 条命令的 mcp_android_run_macro。

不会执行任何形式的命令过滤。 环境变量就是全部控制措施。设置后，这些工具的权限严格涵盖上文所有受门控的操作——pm clear、pm uninstall 和文件删除都可以执行，无需 confirm_destructive，因为 shell 路径根本不会检查该参数。除非连接的 MCP 客户端与设备上的本地 shell 一样可信，否则请勿设置此变量。

后台强制执行

DROIDSIGHT_SENTINEL=1 会启动一个循环，每五秒唤醒一次，并对每个受监控的包重新应用要求维持的状态：使用注册监控时提供的 PIN 唤醒并解锁屏幕、启用无障碍服务、授予悬浮窗权限，以及授予一组运行时权限。只有客户端注册监控项后，才会有监控项；因此，监控列表为空时，启用的 sentinel 只会定时运行。

有两点需要明确说明：

• 它会撤销手动更改。 撤销某个受监控包的权限或禁用其无障碍服务后，五秒内就会恢复。请先移除监控项。
• 它不会要求 confirm_destructive。 该门槛适用于操作人员调用 mcp_android_app_manage 的情况；此循环会直接调用相同的底层操作，因为重新授予权限正是监控项的全部目的。注册监控项即表示同意该监控项之后自行执行的所有操作。

除本地 ADB 连接外，此循环不会进行任何网络 I/O，也不会联系远程服务。

构建和测试

此仓库固定了 Rust 工具链，并将会修改设备的场景排除在默认测试套件之外。

cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked -- --test-threads=1
cargo build --locked --release --bin droidsight

这些检查会在 Linux、macOS 和 Windows 上运行，且无需屏蔽警告即可通过。编译器版本固定在 rust-toolchain.toml 中；单独的 CI 作业会针对 Rust 1.89（声明的最低版本）对 crate 进行类型检查。

修改会影响设备的代码前，请参阅 CONTRIBUTING.md。 SECURITY.md 记录了私下报告、敏感证据脱敏，以及 ADB、主机、MCP、文件系统、日志记录和 shell 的信任边界。参与行为受 CODE_OF_CONDUCT.md 约束。

成熟度

仅在主机上运行的测试套件覆盖了协议解析、架构、序列化、ADB 命令构建、并发发现、重新连接失效处理、设备选择、子进程截止时间、JSON-RPC 批处理、路径限制、shell 引号处理、输出预算、事件监视器拆除、层级结构解析、流程验证、流帧处理与生命周期、静态帧缓存行为、图像编码与坐标元数据、Samsung 锁屏与窗口解析，以及 Intent 故障处理。

发布二进制已通过无线调试在一台运行 Android 13 的 Samsung 设备上进行测试，覆盖设备状态、电池、应用、层级结构和元素快照、OCR、屏幕截图和序列、持续 H.264 捕获、输入和导航、Intent、日志、通知、Wi-Fi 扫描、文件往返、哈希、会话、手势捕获、录制、旋转恢复、崩溃列表和清理。破坏性应用操作、权限操作、无障碍操作、悬浮窗操作、电话服务操作、网络变更、GPS 和电池模拟操作均有意排除在该测试范围之外。其他厂商的设备和 Android 版本仍需单独验证。

H.264 解码

视觉缓存会在进程内使用 openh264 解码 H.264；该库会从源代码构建 Cisco 基于 BSD-2-Clause 许可发布的 C++ 实现。Cisco 的专利授权仅适用于 Cisco 自行发布的二进制文件，不适用于自行编译的构建版本。若要再分发本项目的二进制文件，您有责任满足任何适用的 H.264 专利许可要求。

许可证

MIT。详见 LICENSE。