serve-droid

Una cabina de control compartida en el navegador y un plano de control de agentes para Android. Transmite un emulador o un dispositivo físico, contrólalo desde Chrome o Edge, inspecciona su árbol de interfaz de usuario semántico y Logcat, o entrega la misma sesión a un agente de codificación compatible con MCP.

Estado: versión de desarrollo v0.1. La API pública está versionada, pero el transporte de video y la compatibilidad de dispositivos aún necesitan validación en la matriz de soporte publicada.

npx serve-droid
# → Browser cockpit at a local authenticated URL

Una sesión compartida: los controles compactos del dispositivo activo permanecen a la izquierda mientras la superficie Android en vivo ocupa el espacio de trabajo principal. En pantallas anchas, el inspector de agentes flota contextualmente a la derecha y alterna entre Logcat filtrado, interfaz de usuario semántica y Actividad segura para la privacidad; en ventanas más estrechas, se apila debajo del dispositivo en lugar de reducir la superficie de interacción. La demo determinista también ejercita flujos autenticados de instalación de archivos y portapapeles. No es una validación con dispositivo real; la evidencia de hardware se rastrea por separado en la lista de verificación de lanzamiento.

Lo que obtienes

• Transmisión de dispositivo H.264 en una cabina de navegador receptiva con puntero directo DOWN, eventos MOVE combinados y UP/CANCEL transportados por la misma sesión scrcpy en vivo antes del lanzamiento.

• Desplazamiento con rueda del ratón y trackpad sobre el dispositivo, combinado en gestos táctiles scrcpy acotados para que la entrada de alta resolución del navegador no pueda crear un acumulamiento de comandos del dispositivo.

• Captura de pantalla con un clic desde el fotograma en vivo decodificado, con respaldo autenticado del dispositivo, vista previa, descarga y acciones de portapapeles compatibles con el navegador.

• Segmentación exacta de elementos semánticos que se detiene en coincidencias faltantes o ambiguas.

• Logcat buscable y filtrado por prioridad con controles de pausa, limpieza y copia.

• Controles explícitos de subir/bajar volumen del sistema Android en la barra del dispositivo, separados del silencio de reproducción del navegador.

• Línea de tiempo de Actividad en memoria filtrada por privacidad para eventos recientes estructurados de sesión, dispositivo y control.

• Entrada segura de token LAN y pegado acotado del portapapeles en el campo Android enfocado.

• Arrastrar y soltar APK o transferencia de archivos con progreso de bytes y una fase explícita de procesamiento Android.

• Una observación acotada que contiene la pantalla, la jerarquía de interfaz de usuario, la aplicación en primer plano, el estado del dispositivo y los registros incrementales.

• Las mismas capacidades a través de CLI, API HTTP/WebSocket autenticadas, MCP y una habilidad de agente.

Related MCP server: Android MCP

Por qué

Android Studio refleja dispositivos, scrcpy proporciona una excelente visualización/control nativo, y Maestro es un sólido sistema de automatización de pruebas. serve-droid se centra en un bucle diferente: un humano y un agente de IA compartiendo una sesión de navegador observable durante el desarrollo y la depuración.

Inspiración

La dirección de cabina centrada en el navegador se inspiró en serve-sim de Evan Bacon. serve-droid es una implementación independiente centrada en Android construida alrededor de ADB, transporte scrcpy, Logcat, observaciones semánticas y MCP.

Requisitos

• Node.js 22 o más reciente

• Android SDK Platform Tools con adb en PATH, ANDROID_HOME o ANDROID_SDK_ROOT

• Un emulador o dispositivo Android 8 / API 26+ visible en adb devices -l

• Un navegador actual Chrome, Edge, Safari o Firefox. Chromium usa WebCodecs; Safari y Firefox usan el respaldo de software TinyH264 de mayor costo.

Las Android Platform Tools nunca se descargan silenciosamente ni se redistribuyen.

Inicio rápido

npx serve-droid doctor
npx serve-droid doctor --browser
npx serve-droid avd list
npx serve-droid start --detach
npx serve-droid list --json
npx serve-droid activity --since 0 --json

serve-droid activity lee la misma línea de tiempo de sesión acotada y filtrada por privacidad que muestra el inspector del navegador. Selecciona una sesión en vivo, se autentica internamente con esa sesión y admite la reanudación del cursor sin exponer el token de portador. Consulta la guía de Actividad.

Al seleccionar un puerto fijo, pruébalo antes de tocar el dispositivo. Los puertos ocupados devuelven el código estable PORT_IN_USE y el estado de salida 31; --port 0 mantiene una asignación efímera segura.

npx serve-droid doctor --port 47321 --json
npx serve-droid start --port 47321

El audio de reproducción del dispositivo es opcional y la reproducción del navegador permanece silenciada hasta que un humano la habilita:

npx serve-droid start --audio

Consulta audio y privacidad del dispositivo.

Abre la URL local impresa. El servidor escucha en 127.0.0.1, genera un token aleatorio y lo inyecta en la interfaz local. Para seleccionar un dispositivo:

npx serve-droid --device emulator-5554

Los emuladores instalados se pueden gestionar explícitamente con serve-droid avd start <name> y serve-droid avd stop <serial>. No se descarga ni se licencia contenido del SDK automáticamente; consulta la guía de ciclo de vida de AVD.

Para inspeccionar varios dispositivos conectados con tokens independientes y recursos acotados:

npx serve-droid grid --max-devices 4

Consulta el modelo de seguridad y aislamiento de la cuadrícula de múltiples dispositivos.

Las coordenadas están normalizadas: (0, 0) es la esquina superior izquierda lógica y (1, 1) es la inferior derecha.

npx serve-droid tap 0.5 0.5
npx serve-droid swipe 0.5 0.8 0.5 0.2 --duration 350
npx serve-droid app deep-link 'servedroid://fixture/example'

Las interacciones ADB fallidas conservan errores genéricos a menos que Android informe evidencia explícita de keyguard o política de entrada. Consulta el diagnóstico de fallos de interacción para el contrato DEVICE_LOCKED, SECURE_SCREEN y INPUT_RESTRICTED.

Los punteros directos del navegador ahora transmiten un ciclo de vida autenticado begin → move* → end a través del WebSocket de control mientras el cursor o el dedo aún se mueven. El navegador mantiene una solicitud y un último movimiento pendientes, mientras que el servidor otorga al flujo la propiedad exclusiva de un dedo scrcpy y lo mapea contra un tamaño de fotograma codificado fijo. Si scrcpy no está disponible antes de begin, la solicitud se rechaza antes de la entrada del dispositivo y la cabina usa de forma segura su acción de liberación acotada existente. Después de un begin exitoso, los fallos nunca se reproducen a través de ADB. Un latido escaso en el mismo punto mantiene vivas las pulsaciones largas intencionales, mientras que los flujos abandonados reciben una cancelación de mejor esfuerzo después de dos segundos de inactividad.

En el navegador, pasa el cursor sobre la superficie Android y usa la rueda del ratón o el desplazamiento con dos dedos del trackpad. Una ráfaga se combina en un deslizamiento táctil acotado y anclado al cursor. Los gestos de zoom del navegador asistidos por modificadores no se modifican.

La captura de sesión es explícita y acotada. --record ./recordings almacena el flujo H.264 original más resúmenes de eventos filtrados por privacidad; nunca registra tokens, Logcat, texto escrito, URLs ni contenidos de archivos. Usa --record-controls ./recordings en su lugar para autorizar el inicio/detención del navegador sin grabar inmediatamente; la cabina nunca elige una ruta o límite de host. Consulta la guía de grabación y retención. Las grabaciones finalizadas también se pueden exportar con serve-droid recording trace para inspección de la línea de tiempo en Perfetto.

MCP

{
  "mcpServers": {
    "serve-droid": {
      "command": "npx",
      "args": ["-y", "serve-droid", "mcp"]
    }
  }
}

La superficie MCP proporciona deliberadamente herramientas acotadas explícitas en lugar de acceso arbitrario al shell. Consulta la guía de MCP.

Seguridad

• Enlace solo de bucle local por defecto.

• Autenticación de portador para lecturas, mutaciones, video y control.

• Los WebSockets del navegador llevan credenciales en un encabezado de subprotocolo, no en una URL.

• Sin endpoint arbitrario de ADB o shell del host.

• Las subidas están limitadas a 256 MiB, se escriben en un directorio temporal privado y se eliminan inmediatamente.

• clear y uninstall requieren confirmación explícita de clientes no interactivos.

Lee SECURITY.md antes de enlazar a una interfaz LAN.

El acceso remoto de corta duración a través de un túnel Cloudflare con nombre existente está disponible solo con consentimiento explícito, HTTPS, autenticación de portador y una caducidad estricta. Lee la guía de modelo de amenazas y configuración de túneles antes de usarlo.

Compatible y diferido

v0.1 apunta a macOS, Linux, Windows, Android API 26+, emuladores locales, dispositivos USB, ADB por Wi-Fi, Chrome, Edge, Safari y Firefox. Se incluyen controles de ciclo de vida de AVD instalados, grabación local acotada opcional, el respaldo de navegador TinyH264, audio de dispositivo opcional para API 30+ y soporte opcional de túnel con nombre con caducidad. Los laboratorios de dispositivos en la nube, cuentas, roles multiusuario, creación/aprovisionamiento de AVD, iOS y acceso arbitrario al shell están diferidos. Consulta la matriz de soporte de navegadores.

Desarrollo

pnpm install
pnpm verify
pnpm --filter @serve-droid/cli dev -- doctor

El código fuente del fixture Android está en fixtures/android-test-app. Las pruebas con dispositivo real solo se ejecutan cuando SERVE_DROID_DEVICE_TEST=1 está configurado.

Consulta la lista de verificación de lanzamiento basada en evidencia para el trabajo completado y los hitos restantes de hardware, plataforma y publicación.

TODO del proyecto

• Publicar el repositorio abierto con main protegido, CodeQL, Dependabot y escaneo de secretos.

• Enviar la base compartida de CLI, HTTP/WebSocket, MCP, habilidad de agente y cabina de navegador.

• Añadir una captura de pantalla de cabina reproducible y claramente etiquetada a este README.

• Refinar la cabina del navegador en un espacio de trabajo receptivo centrado en el dispositivo con inspector contextual.

• Añadir controles de Logcat buscables con filtrado por prioridad, pausa, limpieza y copia.

• Añadir Actividad acotada y segura para la privacidad en navegador, CLI y HTTP autenticado.

• Añadir entrega segura de token LAN y controles acotados de portapapeles del navegador.

• Añadir desplazamiento combinado de rueda del ratón y trackpad sobre la superficie Android.

• Enrutar la entrada de puntero y gestos del navegador a través del canal de control scrcpy activo.

• Transmitir el movimiento directo del puntero antes del lanzamiento con combinación y cancelación acotadas.

• Completar la matriz de aceptación de dispositivos reales en macOS, Linux y Windows.

• Publicar y validar el candidato de lanzamiento npm antes de etiquetar v0.1.0.

La lista de verificación completa basada en evidencia se encuentra en docs/TODO.md. Los elementos permanecen sin marcar hasta que el repositorio contenga la implementación o la evidencia externa requerida.

Licencia

Apache-2.0. Consulta THIRD_PARTY_NOTICES.md.