fix(mcp-visualizer): support physical Android devices (#3297)

* fix(mcp-visualizer): support physical Android devices

The visualizer always launched simulator-server with the `android`
subcommand (emulator-only), which panicked on physical Android serials
with "emulator with id <serial> should be running". And even with the
right subcommand it could not find its screen-sharing agent resources
because installSimulatorServer only unpacked the binary, not its
sibling `resources/` tree.

- Plumb a typed StreamDeviceType (android | android_device | ios)
  through DeviceStreamTarget, MaestroConnected, and McpMaestroSession
  so the launch site picks the correct subcommand based on
  Device.DeviceType at the source. Browser carries the field opaquely
  in /api/device/start. Invalid combinations (BROWSER, real iOS) are
  unrepresentable.
- Unpack the entire deps/simulator-server/<platform>/ classpath
  subtree into ~/.maestro/deps/ via a new Unpacker.unpackTree, so
  screen-sharing-agent.jar + per-ABI .so files land next to the
  binary. Uses NIO FileSystems.newFileSystem to share one walker
  across jar and filesystem resources. Verifies all declared
  executableEntries were present so missing-binary packaging bugs
  fail loudly.

* chore(deps): bump simulator-server to f4b4f058

Required by the visualizer fix above: this release adds the
`android_device` subcommand for physical Android and ships the
screen-sharing-agent.jar + per-ABI .so files alongside the binary.

* fix(mcp-visualizer): flush SSE headers on stream open

Ktor 2.3.x's respondBytesWriter buffers the response until the first
write. /api/events/stream has no initial payload, so the browser sees
ERR_EMPTY_RESPONSE on the EventSource and never reconnects, hiding
the entire command log and tap-animation pipeline. The bug has been
latent since the visualizer was introduced in #3288 — exposed now
that physical Android lets us exercise the events path.

Write an SSE comment line on stream open — the standard pattern to
flush headers without producing a data event the client will
misinterpret.

* refactor(mcp): consolidate stream-device-type mapping in createSession

Per pedro18x review: the EMULATOR/REAL→ANDROID/ANDROID_DEVICE mapping
lived in two places (createAndroidSession and StreamDeviceType.forConnected)
and could drift if a new DeviceType lands in one without the other.

Resolve the stream type once at createSession's entry, bail with a
clear unsupported message if forConnected returns null, and pass the
resolved value into the per-platform builders. forConnected becomes
the sole authority. The "real iOS unsupported" check is now subsumed
by the same null branch.

Author: Leland-Takamine

gradle/libs.versions.toml

@@ -50,7 +50,7 @@ picocli = "4.6.3"
 posthog = "1.0.3"
 selenium = "4.43.0"
 selenium-devtools = "4.43.0"
-simulatorServer = "b8534f42"
+simulatorServer = "f4b4f058"
 skiko = "0.8.18"
 squareOkhttp = "4.12.0"
 squareOkio = "3.16.2"

maestro-cli/mcp-visualizer/src/main.tsx

@@ -34,8 +34,11 @@ type DeviceState = {
   message?: string;
 };
 
+type StreamDeviceType = "android" | "android_device" | "ios";
+
 type DeviceTarget = {
   platform: string;
+  deviceType: StreamDeviceType;
   deviceId: string;
 };
 
@@ -704,6 +707,7 @@ function App() {
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         platform: target.platform,
+        deviceType: target.deviceType,
         deviceId: target.deviceId,
       }),
     });

maestro-cli/src/main/java/maestro/cli/Dependencies.kt

@@ -2,6 +2,7 @@ package maestro.cli
 
 import maestro.cli.util.Unpacker.binaryDependency
 import maestro.cli.util.Unpacker.unpack
+import maestro.cli.util.Unpacker.unpackTree
 import maestro.cli.util.EnvUtils
 
 object Dependencies {
@@ -16,9 +17,14 @@ object Dependencies {
     }
 
     fun installSimulatorServer() {
-        unpack(
-            jarPath = "deps/simulator-server/${simulatorServerPlatformDir()}/${simulatorServerBinaryName()}",
-            target = simulatorServer,
+        // simulator-server expects a sibling `resources/` tree (screen-sharing-agent.jar
+        // + per-ABI .so files for physical Android; ffmpeg .so's for linux), so unpack
+        // the whole platform subtree rather than just the binary.
+        val binaryName = simulatorServerBinaryName()
+        unpackTree(
+            classpathPrefix = "deps/simulator-server/${simulatorServerPlatformDir()}",
+            targetDir = simulatorServer.parentFile,
+            executableEntries = setOf(binaryName),
         )
     }
 

maestro-cli/src/main/java/maestro/cli/mcp/McpMaestroSessionManager.kt

@@ -7,6 +7,7 @@ import maestro.Maestro
 import maestro.cli.CliError
 import maestro.cli.mcp.visualizer.McpVisualizerDriver
 import maestro.cli.mcp.visualizer.McpVisualizerEvents
+import maestro.cli.mcp.visualizer.StreamDeviceType
 import maestro.cli.mcp.visualizer.VisualizerEvent
 import maestro.cli.report.TestDebugReporter
 import maestro.device.DeviceService
@@ -41,7 +42,11 @@ internal class McpMaestroSessionManager : AutoCloseable {
 
     private fun publishConnected(session: McpMaestroSession) {
         McpVisualizerEvents.publish(
-            VisualizerEvent.MaestroConnected(platform = session.platform, deviceId = session.deviceId)
+            VisualizerEvent.MaestroConnected(
+                platform = session.platform,
+                deviceType = session.streamDeviceType,
+                deviceId = session.deviceId,
+            )
         )
     }
 
@@ -60,33 +65,49 @@ internal class McpMaestroSessionManager : AutoCloseable {
         val device = DeviceService.listConnectedDevices()
             .find { it.instanceId.equals(deviceId, ignoreCase = true) }
             ?: throw CliError("Device with id $deviceId is not connected")
-        if (device.platform == Platform.IOS && device.deviceType == Device.DeviceType.REAL) {
-            throw UnsupportedOperationException("Real iOS devices are not yet supported by the MCP server")
-        }
+        val streamDeviceType = StreamDeviceType.forConnected(device)
+            ?: throw UnsupportedOperationException(
+                "Device ${device.instanceId} (${device.platform}/${device.deviceType}) is not supported by the MCP server"
+            )
 
         return when (device.platform) {
-            Platform.ANDROID -> createAndroidSession(device)
-            Platform.IOS -> createIosSession(device)
+            Platform.ANDROID -> createAndroidSession(device, streamDeviceType)
+            Platform.IOS -> createIosSession(device, streamDeviceType)
             Platform.WEB -> createWebSession()
         }
     }
 
-    private fun createAndroidSession(device: Device.Connected): McpMaestroSession {
+    private fun createAndroidSession(device: Device.Connected, streamDeviceType: StreamDeviceType): McpMaestroSession {
         val dadb = Dadb.list().find { it.toString() == device.instanceId }
             ?: error("Unable to find device with id ${device.instanceId}")
         val driver = McpVisualizerDriver(AndroidDriver(dadb, null, device.instanceId, true), "android")
-        return McpMaestroSession(Maestro.android(driver), platform = "android", deviceId = device.instanceId)
+        return McpMaestroSession(
+            maestro = Maestro.android(driver),
+            platform = "android",
+            streamDeviceType = streamDeviceType,
+            deviceId = device.instanceId,
+        )
     }
 
-    private fun createIosSession(device: Device.Connected): McpMaestroSession {
+    private fun createIosSession(device: Device.Connected, streamDeviceType: StreamDeviceType): McpMaestroSession {
         val driver = McpVisualizerDriver(createIOSDriver(device.instanceId, device.deviceType), "ios")
-        return McpMaestroSession(Maestro.ios(driver, openDriver = true), platform = "ios", deviceId = device.instanceId)
+        return McpMaestroSession(
+            maestro = Maestro.ios(driver, openDriver = true),
+            platform = "ios",
+            streamDeviceType = streamDeviceType,
+            deviceId = device.instanceId,
+        )
     }
 
     private fun createWebSession(): McpMaestroSession {
         val driver = McpVisualizerDriver(CdpWebDriver(isStudio = false, isHeadless = false, screenSize = null), "web")
         driver.open()
-        return McpMaestroSession(Maestro(driver), platform = "web", deviceId = WEB_DEVICE_ID)
+        return McpMaestroSession(
+            maestro = Maestro(driver),
+            platform = "web",
+            streamDeviceType = null,
+            deviceId = WEB_DEVICE_ID,
+        )
     }
 
     private fun createIOSDriver(
@@ -146,6 +167,8 @@ internal class McpMaestroSessionManager : AutoCloseable {
     data class McpMaestroSession(
         val maestro: Maestro,
         val platform: String,
+        // null for web sessions, which the visualizer doesn't stream.
+        val streamDeviceType: StreamDeviceType?,
         val deviceId: String,
     ) {
         fun close() {

maestro-cli/src/main/java/maestro/cli/mcp/visualizer/McpVisualizerEvents.kt

@@ -17,6 +17,8 @@ internal sealed interface VisualizerEvent {
 
     data class MaestroConnected(
         val platform: String,
+        // null for web sessions, which the visualizer doesn't stream.
+        val deviceType: StreamDeviceType?,
         val deviceId: String,
     ) : VisualizerEvent
 

maestro-cli/src/main/java/maestro/cli/mcp/visualizer/McpVisualizerServer.kt

@@ -1,5 +1,7 @@
 package maestro.cli.mcp.visualizer
 
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonValue
 import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import com.fasterxml.jackson.module.kotlin.readValue
@@ -33,6 +35,7 @@ import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import maestro.cli.Dependencies
 import maestro.cli.util.getFreePort
+import maestro.device.Device
 import maestro.device.DeviceService
 import maestro.device.Platform
 import java.io.BufferedReader
@@ -49,7 +52,36 @@ internal data class DeviceStreamState(
     val message: String? = null,
 )
 
-private data class DeviceStreamTarget(val platform: String, val deviceId: String)
+// The subset of devices simulator-server can stream, plus the wire/CLI name for each.
+// Mirrors simulator-server's subcommands; using an enum keeps invalid combinations
+// (BROWSER, real iOS, etc.) unrepresentable at the call sites.
+internal enum class StreamDeviceType(@JsonValue val wire: String) {
+    ANDROID("android"),
+    ANDROID_DEVICE("android_device"),
+    IOS("ios"),
+    ;
+
+    companion object {
+        @JvmStatic
+        @JsonCreator
+        fun fromWire(value: String): StreamDeviceType =
+            entries.firstOrNull { it.wire == value }
+                ?: throw IllegalArgumentException("Unknown StreamDeviceType: '$value'")
+
+        fun forConnected(device: Device.Connected): StreamDeviceType? = when {
+            device.platform == Platform.ANDROID && device.deviceType == Device.DeviceType.EMULATOR -> ANDROID
+            device.platform == Platform.ANDROID && device.deviceType == Device.DeviceType.REAL -> ANDROID_DEVICE
+            device.platform == Platform.IOS && device.deviceType == Device.DeviceType.SIMULATOR -> IOS
+            else -> null
+        }
+    }
+}
+
+private data class DeviceStreamTarget(
+    val platform: String,
+    val deviceType: StreamDeviceType,
+    val deviceId: String,
+)
 
 internal class McpVisualizerServer private constructor(
     val port: Int,
@@ -88,15 +120,21 @@ internal class McpVisualizerServer private constructor(
             suspend fun deviceStreamTargets(): List<DeviceStreamTarget> =
                 withContext(Dispatchers.IO) {
                     DeviceService.listConnectedDevices()
-                        .filter { it.platform != Platform.WEB }
-                        .map { DeviceStreamTarget(it.platform.name.lowercase(), it.instanceId) }
+                        .mapNotNull { device ->
+                            val type = StreamDeviceType.forConnected(device) ?: return@mapNotNull null
+                            DeviceStreamTarget(
+                                platform = device.platform.name.lowercase(),
+                                deviceType = type,
+                                deviceId = device.instanceId,
+                            )
+                        }
                 }
 
             val eventRegistration = McpVisualizerEvents.register { event ->
                 scope.launch {
                     events.publish(event)
-                    if (event is VisualizerEvent.MaestroConnected && event.platform != "web") {
-                        deviceStream.start(event.platform, event.deviceId)
+                    if (event is VisualizerEvent.MaestroConnected && event.deviceType != null) {
+                        deviceStream.start(event.platform, event.deviceType, event.deviceId)
                     }
                 }
             }
@@ -126,15 +164,20 @@ internal class McpVisualizerServer private constructor(
                     get("/api/device/state") { deviceStates.stream(call, deviceStream.state) }
                     get("/api/device/targets") { call.respondJson(mapOf("devices" to deviceStreamTargets())) }
                     post("/api/device/start") {
-                        data class Request(val platform: String? = null, val deviceId: String? = null)
+                        data class Request(
+                            val platform: String? = null,
+                            val deviceType: StreamDeviceType? = null,
+                            val deviceId: String? = null,
+                        )
                         val request = runCatching { mapper.readValue<Request>(call.receiveText()) }.getOrNull()
                         val platform = request?.platform
+                        val deviceType = request?.deviceType
                         val deviceId = request?.deviceId
-                        if (platform.isNullOrBlank() || deviceId.isNullOrBlank()) {
-                            call.respondJson(mapOf("error" to "platform and deviceId are required"), HttpStatusCode.BadRequest)
+                        if (platform.isNullOrBlank() || deviceType == null || deviceId.isNullOrBlank()) {
+                            call.respondJson(mapOf("error" to "platform, deviceType, and deviceId are required"), HttpStatusCode.BadRequest)
                             return@post
                         }
-                        call.respondJson(deviceStream.start(platform, deviceId))
+                        call.respondJson(deviceStream.start(platform, deviceType, deviceId))
                     }
                     post("/api/device/input") {
                         // Opaque proxy to simulator-server's stdin: the browser owns the protocol
@@ -186,7 +229,7 @@ private class DeviceStream(
         Runtime.getRuntime().addShutdownHook(Thread { process?.destroyForcibly() })
     }
 
-    suspend fun start(platform: String, deviceId: String): DeviceStreamState = startLock.withLock {
+    suspend fun start(platform: String, deviceType: StreamDeviceType, deviceId: String): DeviceStreamState = startLock.withLock {
         val current = state
         if (current.platform == platform && current.deviceId == deviceId &&
             (current.status == "starting" || current.status == "streaming")) {
@@ -200,7 +243,7 @@ private class DeviceStream(
             Dependencies.installSimulatorServer()
             val p = ProcessBuilder(
                 Dependencies.simulatorServerBinary().absolutePath,
-                platform, "--id", deviceId,
+                deviceType.wire, "--id", deviceId,
             ).redirectErrorStream(false).start()
             process = p
             stdinWriter = OutputStreamWriter(p.outputStream)
@@ -296,6 +339,11 @@ private class SseBroadcaster(private val mapper: ObjectMapper) {
             val client = SseClient(this)
             clients.add(client)
             try {
+                // Flush headers immediately with an SSE comment. Ktor 2.3.x buffers the
+                // response until the first write, so a stream with no initial payload
+                // (e.g. /api/events/stream before any event fires) looks like an empty
+                // response to the browser and EventSource errors out with ERR_EMPTY_RESPONSE.
+                client.write(": ready\n\n")
                 if (initialValue != null) {
                     client.write("data: ${mapper.writeValueAsString(initialValue)}\n\n")
                 }