@bdayadev/flutter-ultra-mcp 0.0.0 → 1.0.1

package/packages/flutter-ultra-native-desktop/README.md

@@ -1,131 +1,131 @@
-# @flutter-ultra/flutter-ultra-native-desktop
-
-Cross-platform MCP server for **native desktop UI automation** — drives the
-OS-level a11y tree on macOS (AXUIElement via a Swift sidecar), Windows (UIA
-via a FlaUI C# sidecar), and Linux (AT-SPI 2 via a PyGObject sidecar). Used
-by Claude Code skills to introspect dialogs, click buttons, type text, and
-capture window screenshots in apps that Flutter's VM service can't reach.
-
-## Architecture
-
-A single platform sidecar process is spawned per MCP-server lifetime. On
-crash the cached entry is dropped and the next tool invocation respawns it.
-Tool handlers stay platform-agnostic — the `DesktopBackend` interface
-(`src/types.ts`) hides every OS-specific quirk. `src/index.ts` switches on
-`process.platform` and selects `MacDesktopBackend`, `WinDesktopBackend`, or
-`LinuxDesktopBackend` accordingly; the registry registers tools only when
-the backend reports `helperPresent && permissionGranted`.
-
-## Tool surface (9 tools, plan §5.6)
-
-| Tool                    | Purpose                                                                  |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `list_windows`          | Visible top-level windows, optionally filtered by process / title.       |
-| `dump_window_tree`      | Full a11y tree for a window, depth-bounded.                              |
-| `desktop_query`         | XPath subset: `//role`, `//role[@name="X"]`, `//*[@label~="X"]`.         |
-| `desktop_click`         | Click by element id (preferred) or screen coordinates.                   |
-| `desktop_type`          | Type text; optionally clear field first; optional element focus.         |
-| `desktop_screenshot`    | PNG (base64) — window or full screen.                                    |
-| `select_file_in_dialog` | Type a path into the frontmost file dialog + click Open/Save.            |
-| `confirm_dialog`        | Click a dialog button by intent (allow/deny/ok/cancel/yes/no/open/save). |
-| `wait_for_window`       | Poll for a window matching title regex / process; configurable timeout.  |
-
-Zero tools register when the per-OS sidecar is missing or the a11y bus is
-unreachable (AC-ND4). Startup logs explain why so users can self-remediate.
-
-## Linux path — AT-SPI via PyGObject
-
-The Linux backend invokes `python3 -u -m atspi_bridge` from the package's
-`sidecars/linux-atspi/` directory. The Python sidecar:
-
-- Wraps `gi.repository.Atspi` for window enumeration, accessible-tree
-  introspection, and action invocation (`Action.do_action` for click,
-  `EditableText.insert_text` for type).
-- Shells out to `grim` on Wayland or `scrot`/`import` on X11 for
-  screenshots. Both branches required because Wayland sandboxing makes
-  X11 screenshot APIs unusable.
-- Shells out to `xdotool` (X11) or `ydotool` (Wayland) for
-  cursor-coordinate input synthesis when AT-SPI alone can't reach a
-  widget (Flutter Linux desktop is the common case — its custom-painted
-  widgets don't expose the EditableText interface).
-
-### Distro support
-
-| Distro family                | Install command                                                    |
-| ---------------------------- | ------------------------------------------------------------------ |
-| Debian / Ubuntu / Mint / Pop | `sudo apt-get install -y python3-gi gir1.2-atspi-2.0 at-spi2-core` |
-| Fedora / RHEL / Rocky / Alma | `sudo dnf install -y python3-gobject atspi at-spi2-core`           |
-| Arch / Manjaro / EndeavourOS | `sudo pacman -S --needed python-gobject at-spi2-core`              |
-| openSUSE (Leap & Tumbleweed) | `sudo zypper install -y python3-gobject typelib-1_0-Atspi-2_0`     |
-| Alpine                       | `sudo apk add py3-gobject3 at-spi2-core`                           |
-
-Use the exported `detectLocalDistro()` helper to print the exact command
-for the running host.
-
-### Wayland caveat
-
-AT-SPI works fully on **X11**. On **Wayland** the coverage varies by
-toolkit:
-
-| Toolkit                                        | Coverage                                                        |
-| ---------------------------------------------- | --------------------------------------------------------------- |
-| GTK 3 / GTK 4                                  | Fully exposed                                                   |
-| Qt 5 / Qt 6 with `QT_ACCESSIBILITY=1`          | Fully exposed                                                   |
-| Electron with `--force-renderer-accessibility` | Fully exposed                                                   |
-| Flutter Linux desktop                          | Active window only (flutter/flutter#107016) — use ultra_flutter |
-
-When `XDG_SESSION_TYPE=wayland` the backend sets `capabilities.waylandLimited
-= true` so the registry can present a one-shot warning. For Flutter Linux
-apps prefer the in-app `ultra_flutter` binding via
-`@flutter-ultra/flutter-ultra-gesture` / `@flutter-ultra/flutter-ultra-runtime`.
-
-### Headless / minimal compositors
-
-Sway, river, and hyprland do NOT auto-spawn `at-spi-dbus-bus`. Enable it
-explicitly:
-
-```bash
-systemctl --user enable --now at-spi-dbus-bus
-```
-
-GNOME, KDE, XFCE, MATE, and Cinnamon auto-spawn it on session start.
-
-## Device router placeholder
-
-The TS server consumes the `Device` interface from `src/device/types.ts`.
-Today only `LocalDevice` ships; SSH and WSL `Device` implementations land
-post-wave-3 in `@flutter-ultra/device-router`. The Python sidecar runs
-inside the target Linux environment (local host, WSL distro, or remote
-SSH-Linux); the TS server stays on the MCP host and pipes JSON-RPC across
-stdio. No backend code changes when the router lands — the platform
-switch in `src/index.ts` keeps using `new LocalDevice()` until the router
-swaps it for `routerDevice.select(deviceId)`.
-
-## Development
-
-```bash
-# Repo root
-npm ci
-npm run -w @flutter-ultra/flutter-ultra-native-desktop build
-npm run -w @flutter-ultra/flutter-ultra-native-desktop test
-npm run -w @flutter-ultra/flutter-ultra-native-desktop typecheck
-
-# Python sidecar tests (Linux only)
-cd packages/flutter-ultra-native-desktop/sidecars/linux-atspi
-sudo apt-get install -y python3-gi gir1.2-atspi-2.0 at-spi2-core
-pip install pytest
-PYTHONPATH=. pytest tests/
-```
-
-## CI
-
-| Workflow                              | Purpose                                                             |
-| ------------------------------------- | ------------------------------------------------------------------- |
-| `.github/workflows/ci.yml`            | Cross-platform TS unit tests (ubuntu/macos/windows × Node 20/22)    |
-| `.github/workflows/sidecar-macos.yml` | Build the Swift helper on macos-latest + TCC probe smoke            |
-| `.github/workflows/sidecar-linux.yml` | Python sidecar pytest matrix + Xvfb-driven AT-SPI integration smoke |
-
-## Status
-
-Wave 3 complete. macOS path merged via PR #17 (worker-J). Linux path
-shipped in this PR (worker-K). Windows path in flight (worker-I).
+# @flutter-ultra/flutter-ultra-native-desktop
+
+Cross-platform MCP server for **native desktop UI automation** — drives the
+OS-level a11y tree on macOS (AXUIElement via a Swift sidecar), Windows (UIA
+via a FlaUI C# sidecar), and Linux (AT-SPI 2 via a PyGObject sidecar). Used
+by Claude Code skills to introspect dialogs, click buttons, type text, and
+capture window screenshots in apps that Flutter's VM service can't reach.
+
+## Architecture
+
+A single platform sidecar process is spawned per MCP-server lifetime. On
+crash the cached entry is dropped and the next tool invocation respawns it.
+Tool handlers stay platform-agnostic — the `DesktopBackend` interface
+(`src/types.ts`) hides every OS-specific quirk. `src/index.ts` switches on
+`process.platform` and selects `MacDesktopBackend`, `WinDesktopBackend`, or
+`LinuxDesktopBackend` accordingly; the registry registers tools only when
+the backend reports `helperPresent && permissionGranted`.
+
+## Tool surface (9 tools, plan §5.6)
+
+| Tool                    | Purpose                                                                  |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `list_windows`          | Visible top-level windows, optionally filtered by process / title.       |
+| `dump_window_tree`      | Full a11y tree for a window, depth-bounded.                              |
+| `desktop_query`         | XPath subset: `//role`, `//role[@name="X"]`, `//*[@label~="X"]`.         |
+| `desktop_click`         | Click by element id (preferred) or screen coordinates.                   |
+| `desktop_type`          | Type text; optionally clear field first; optional element focus.         |
+| `desktop_screenshot`    | PNG (base64) — window or full screen.                                    |
+| `select_file_in_dialog` | Type a path into the frontmost file dialog + click Open/Save.            |
+| `confirm_dialog`        | Click a dialog button by intent (allow/deny/ok/cancel/yes/no/open/save). |
+| `wait_for_window`       | Poll for a window matching title regex / process; configurable timeout.  |
+
+Zero tools register when the per-OS sidecar is missing or the a11y bus is
+unreachable (AC-ND4). Startup logs explain why so users can self-remediate.
+
+## Linux path — AT-SPI via PyGObject
+
+The Linux backend invokes `python3 -u -m atspi_bridge` from the package's
+`sidecars/linux-atspi/` directory. The Python sidecar:
+
+- Wraps `gi.repository.Atspi` for window enumeration, accessible-tree
+  introspection, and action invocation (`Action.do_action` for click,
+  `EditableText.insert_text` for type).
+- Shells out to `grim` on Wayland or `scrot`/`import` on X11 for
+  screenshots. Both branches required because Wayland sandboxing makes
+  X11 screenshot APIs unusable.
+- Shells out to `xdotool` (X11) or `ydotool` (Wayland) for
+  cursor-coordinate input synthesis when AT-SPI alone can't reach a
+  widget (Flutter Linux desktop is the common case — its custom-painted
+  widgets don't expose the EditableText interface).
+
+### Distro support
+
+| Distro family                | Install command                                                    |
+| ---------------------------- | ------------------------------------------------------------------ |
+| Debian / Ubuntu / Mint / Pop | `sudo apt-get install -y python3-gi gir1.2-atspi-2.0 at-spi2-core` |
+| Fedora / RHEL / Rocky / Alma | `sudo dnf install -y python3-gobject atspi at-spi2-core`           |
+| Arch / Manjaro / EndeavourOS | `sudo pacman -S --needed python-gobject at-spi2-core`              |
+| openSUSE (Leap & Tumbleweed) | `sudo zypper install -y python3-gobject typelib-1_0-Atspi-2_0`     |
+| Alpine                       | `sudo apk add py3-gobject3 at-spi2-core`                           |
+
+Use the exported `detectLocalDistro()` helper to print the exact command
+for the running host.
+
+### Wayland caveat
+
+AT-SPI works fully on **X11**. On **Wayland** the coverage varies by
+toolkit:
+
+| Toolkit                                        | Coverage                                                        |
+| ---------------------------------------------- | --------------------------------------------------------------- |
+| GTK 3 / GTK 4                                  | Fully exposed                                                   |
+| Qt 5 / Qt 6 with `QT_ACCESSIBILITY=1`          | Fully exposed                                                   |
+| Electron with `--force-renderer-accessibility` | Fully exposed                                                   |
+| Flutter Linux desktop                          | Active window only (flutter/flutter#107016) — use ultra_flutter |
+
+When `XDG_SESSION_TYPE=wayland` the backend sets `capabilities.waylandLimited
+= true` so the registry can present a one-shot warning. For Flutter Linux
+apps prefer the in-app `ultra_flutter` binding via
+`@flutter-ultra/flutter-ultra-gesture` / `@flutter-ultra/flutter-ultra-runtime`.
+
+### Headless / minimal compositors
+
+Sway, river, and hyprland do NOT auto-spawn `at-spi-dbus-bus`. Enable it
+explicitly:
+
+```bash
+systemctl --user enable --now at-spi-dbus-bus
+```
+
+GNOME, KDE, XFCE, MATE, and Cinnamon auto-spawn it on session start.
+
+## Device router placeholder
+
+The TS server consumes the `Device` interface from `src/device/types.ts`.
+Today only `LocalDevice` ships; SSH and WSL `Device` implementations land
+post-wave-3 in `@flutter-ultra/device-router`. The Python sidecar runs
+inside the target Linux environment (local host, WSL distro, or remote
+SSH-Linux); the TS server stays on the MCP host and pipes JSON-RPC across
+stdio. No backend code changes when the router lands — the platform
+switch in `src/index.ts` keeps using `new LocalDevice()` until the router
+swaps it for `routerDevice.select(deviceId)`.
+
+## Development
+
+```bash
+# Repo root
+npm ci
+npm run -w @flutter-ultra/flutter-ultra-native-desktop build
+npm run -w @flutter-ultra/flutter-ultra-native-desktop test
+npm run -w @flutter-ultra/flutter-ultra-native-desktop typecheck
+
+# Python sidecar tests (Linux only)
+cd packages/flutter-ultra-native-desktop/sidecars/linux-atspi
+sudo apt-get install -y python3-gi gir1.2-atspi-2.0 at-spi2-core
+pip install pytest
+PYTHONPATH=. pytest tests/
+```
+
+## CI
+
+| Workflow                              | Purpose                                                             |
+| ------------------------------------- | ------------------------------------------------------------------- |
+| `.github/workflows/ci.yml`            | Cross-platform TS unit tests (ubuntu/macos/windows × Node 20/22)    |
+| `.github/workflows/sidecar-macos.yml` | Build the Swift helper on macos-latest + TCC probe smoke            |
+| `.github/workflows/sidecar-linux.yml` | Python sidecar pytest matrix + Xvfb-driven AT-SPI integration smoke |
+
+## Status
+
+Wave 3 complete. macOS path merged via PR #17 (worker-J). Linux path
+shipped in this PR (worker-K). Windows path in flight (worker-I).

package/packages/flutter-ultra-native-desktop/package.json

@@ -1,81 +1,81 @@
-{
-  "name": "@flutter-ultra/flutter-ultra-native-desktop",
-  "version": "0.0.1",
-  "private": false,
-  "description": "MCP server for native desktop UIs: Windows UIA (FlaUI sidecar), macOS AXUIElement (Swift sidecar + TCC UX), Linux AT-SPI (PyGObject sidecar). Cross-OS feature detection registers ZERO tools per OS path when its sidecar is unavailable.",
-  "license": "Apache-2.0",
-  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/packages/flutter-ultra-native-desktop",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
-    "directory": "packages/flutter-ultra-native-desktop"
-  },
-  "bugs": {
-    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
-  },
-  "keywords": [
-    "mcp",
-    "desktop",
-    "axuielement",
-    "accessibility",
-    "macos",
-    "tcc",
-    "ui-automation",
-    "at-spi",
-    "atspi",
-    "linux",
-    "pygobject"
-  ],
-  "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "flutter-ultra-native-desktop": "dist/bin.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md",
-    "sidecars/macos-swift/Package.swift",
-    "sidecars/macos-swift/Sources",
-    "sidecars/macos-swift/bin",
-    "sidecars/macos-swift/README.md",
-    "sidecars/windows-flaui/FlutterUltraWinHelper",
-    "sidecars/windows-flaui/README.md",
-    "sidecars/linux-atspi/atspi_bridge",
-    "sidecars/linux-atspi/pyproject.toml",
-    "sidecars/linux-atspi/requirements.txt",
-    "sidecars/linux-atspi/README.md"
-  ],
-  "scripts": {
-    "build": "tsc -b",
-    "build:sidecar:windows": "dotnet publish sidecars/windows-flaui/FlutterUltraWinHelper/FlutterUltraWinHelper.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:PublishTrimmed=false -o sidecars/windows-flaui/bin",
-    "lint": "eslint src",
-    "test": "vitest run",
-    "typecheck": "tsc -b --noEmit",
-    "clean": "rimraf dist .turbo *.tsbuildinfo sidecars/windows-flaui/bin sidecars/windows-flaui/FlutterUltraWinHelper/bin sidecars/windows-flaui/FlutterUltraWinHelper/obj"
-  },
-  "dependencies": {
-    "@flutter-ultra/mcp-runtime": "^0.0.1",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "rimraf": "^6.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@flutter-ultra/flutter-ultra-native-desktop",
+  "version": "0.0.1",
+  "private": true,
+  "description": "MCP server for native desktop UIs: Windows UIA (FlaUI sidecar), macOS AXUIElement (Swift sidecar + TCC UX), Linux AT-SPI (PyGObject sidecar). Cross-OS feature detection registers ZERO tools per OS path when its sidecar is unavailable.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/packages/flutter-ultra-native-desktop",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "packages/flutter-ultra-native-desktop"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "desktop",
+    "axuielement",
+    "accessibility",
+    "macos",
+    "tcc",
+    "ui-automation",
+    "at-spi",
+    "atspi",
+    "linux",
+    "pygobject"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-native-desktop": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "sidecars/macos-swift/Package.swift",
+    "sidecars/macos-swift/Sources",
+    "sidecars/macos-swift/bin",
+    "sidecars/macos-swift/README.md",
+    "sidecars/windows-flaui/FlutterUltraWinHelper",
+    "sidecars/windows-flaui/README.md",
+    "sidecars/linux-atspi/atspi_bridge",
+    "sidecars/linux-atspi/pyproject.toml",
+    "sidecars/linux-atspi/requirements.txt",
+    "sidecars/linux-atspi/README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "build:sidecar:windows": "dotnet publish sidecars/windows-flaui/FlutterUltraWinHelper/FlutterUltraWinHelper.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:PublishTrimmed=false -o sidecars/windows-flaui/bin",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo sidecars/windows-flaui/bin sidecars/windows-flaui/FlutterUltraWinHelper/bin sidecars/windows-flaui/FlutterUltraWinHelper/obj"
+  },
+  "dependencies": {
+    "@flutter-ultra/mcp-runtime": "^0.0.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/flutter-ultra-native-mobile/README.md

@@ -1,103 +1,103 @@
-# `@flutter-ultra/flutter-ultra-native-mobile`
-
-MCP server for **native mobile overlay automation**: Android UIAutomator via `adb`, iOS XCUITest via `xcrun simctl` (simulators, Mac only) and `go-ios` (physical devices). Owns the **Chrome Custom Tabs / SafariViewController OAuth** problem with the `solve_oauth_cct` composite tool — see [plan §5.5.1](../../docs/) for the full design.
-
-Part of the **Flutter Ultra MCP** plugin for Claude Code. The server runs as one of the eight MCP processes registered in `.mcp.json`.
-
-## Tool catalogue
-
-| Tool                                                          | Class | Purpose                                                 |
-| ------------------------------------------------------------- | ----- | ------------------------------------------------------- |
-| `list_devices`                                                | quick | Enumerate Android + iOS (sim + physical) devices        |
-| `dump_a11y_tree`                                              | long  | Dump UIAutomator XML / XCUITest a11y as structured tree |
-| `wait_for_native_element`                                     | long  | Poll the a11y tree until a finder matches               |
-| `native_tap`                                                  | quick | Tap by coordinates or finder (bounds-center)            |
-| `native_type`                                                 | quick | Type into focused input                                 |
-| `native_swipe`                                                | quick | Swipe between two coordinates                           |
-| `native_back` / `_home` / `_app_switch` / `_open_settings`    | quick | System keys / intents                                   |
-| `native_pin_lock`                                             | quick | Toggle Android lock-task (kiosk mode)                   |
-| `dismiss_permission_dialog`                                   | quick | Smart allow/deny on runtime permission prompt           |
-| `native_permission_grant` / `_deny`                           | quick | `pm grant` / `pm revoke`                                |
-| `take_device_screenshot`                                      | quick | Base64 PNG via image content                            |
-| `set_device_orientation`                                      | quick | Portrait / landscape                                    |
-| `native_clipboard_set` / `_get`                               | quick | Device clipboard                                        |
-| `start_device_logs` / `poll_device_logs` / `stop_device_logs` | quick | Split-tool logcat / oslog tail                          |
-| `solve_oauth_cct`                                             | long  | CCT/SVC OAuth via Playwright + deep-link dispatch       |
-
-All long-running tools are wrapped by the shared `runWithWatchdog` so the 60-second MCP client ceiling never kills them.
-
-## Architecture
-
-Every tool routes shell commands through a `Device` abstraction:
-
-```text
-Tool handler ─► registry.get(deviceId) ─► AndroidDevice  ─► adb -s <udid> ...
-                                       ─► IosSimDevice   ─► xcrun simctl ...
-                                       ─► IosPhysicalDev ─► go-ios       ...
-```
-
-`AndroidDevice` / `IosSimDevice` / `IosPhysicalDevice` all implement the same `DeviceTransport` interface (`shell()`, `upload()`, `download()`, `isAlive()`, `dispose()`). A future remote-device adapter (WSL, SSH) drops in by implementing the same interface — no tool code changes.
-
-```mermaid
-flowchart LR
-    A[Tool handler] --> R[DeviceRegistry]
-    R -->|cached| D[DeviceTransport]
-    D --> Adb[AndroidDevice<br/>adb -s udid]
-    D --> Sim[IosSimDevice<br/>xcrun simctl]
-    D --> Phy[IosPhysicalDevice<br/>go-ios]
-    D -.future.-> Ssh[SshDevice<br/>ssh user@host adb ...]
-    D -.future.-> Wsl[WslDevice<br/>wsl -- adb ...]
-```
-
-## CCT OAuth bypass — `solve_oauth_cct`
-
-Chrome Custom Tabs and SafariViewController hide the OAuth flow behind a system-owned web view that no UI driver can introspect. We do **not** try to drive CCT directly. Instead:
-
-1. Launch Playwright Chromium with the provider's `authorize` URL.
-2. Submit credentials (optional `fillFlow`) — pause for human MFA when needed.
-3. Intercept the redirect to the app scheme (`com.example.myapp://callback?code=…`) before Chromium drops it as `ERR_UNKNOWN_URL_SCHEME`.
-4. Deliver the same URL into the app via `Device.shell()`:
-   - Android: `adb shell am start -W -a android.intent.action.VIEW -d <url>`
-   - iOS Sim: `xcrun simctl openurl <udid> <url>`
-   - iOS physical: requires `idb` (out of scope for this server today).
-
-The Flutter app's deep-link handler cannot distinguish the dispatched intent from a real CCT close — the same `Intent.ACTION_VIEW` arrives with the same URL. PKCE state stays valid because the app initiated the flow (its `code_verifier` is in its own memory).
-
-## Configuration
-
-| Env var                                   | Default      | Purpose                                 |
-| ----------------------------------------- | ------------ | --------------------------------------- |
-| `FLUTTER_ULTRA_ADB`                       | `adb`        | Path to the `adb` binary                |
-| `FLUTTER_ULTRA_XCRUN`                     | `xcrun`      | Path to `xcrun`                         |
-| `FLUTTER_ULTRA_GO_IOS_BIN`                | `ios`        | Path to the go-ios `ios` CLI            |
-| `FLUTTER_ULTRA_TOOL_TIMEOUT_<NAME_UPPER>` | tool default | Override per-tool watchdog ceiling (ms) |
-| `FLUTTER_ULTRA_LOG_LEVEL`                 | `info`       | `debug` / `info` / `warn` / `error`     |
-
-## Platform support
-
-| Tool                                 | Linux             | macOS | Windows                        |
-| ------------------------------------ | ----------------- | ----- | ------------------------------ |
-| Android tools                        | yes (adb on PATH) | yes   | yes                            |
-| iOS Simulator tools                  | no                | yes   | no                             |
-| iOS physical (go-ios)                | yes               | yes   | yes (depends on go-ios binary) |
-| `solve_oauth_cct` (Android dispatch) | yes               | yes   | yes                            |
-| `solve_oauth_cct` (iOS sim dispatch) | no                | yes   | no                             |
-
-iOS tools called on non-darwin hosts return a structured "unsupported" payload (per AC-NM3) — they do not crash the server.
-
-## Acceptance criteria
-
-- **AC-NM1** — `dismiss_permission_dialog(intent='allow')` clears a runtime permission within 3s on the Android emulator.
-- **AC-NM2** — On iOS Simulator (Mac), `native_tap` on a SafariViewController OAuth login button completes the flow combined with `wait_for_url`.
-- **AC-NM3** — iOS tools cleanly return `unsupported` on win32 / linux.
-- **AC-NM4** — `solve_oauth_cct` end-to-end completes an OIDC OAuth flow against your identity provider on Android emulator within 60s.
-
-## Development
-
-```bash
-npm install                                    # at repo root
-npm run -w @flutter-ultra/flutter-ultra-native-mobile build
-npm run -w @flutter-ultra/flutter-ultra-native-mobile test
-```
-
-The unit-test suite focuses on the host-side parsers (`adb devices -l`, UIAutomator XML, simctl JSON) and the `Device` abstraction — full device-loop tests require an attached Android emulator and live in the cross-platform e2e workflow.
+# `@flutter-ultra/flutter-ultra-native-mobile`
+
+MCP server for **native mobile overlay automation**: Android UIAutomator via `adb`, iOS XCUITest via `xcrun simctl` (simulators, Mac only) and `go-ios` (physical devices). Owns the **Chrome Custom Tabs / SafariViewController OAuth** problem with the `solve_oauth_cct` composite tool — see [plan §5.5.1](../../docs/) for the full design.
+
+Part of the **Flutter Ultra MCP** plugin for Claude Code. The server runs as one of the eight MCP processes registered in `.mcp.json`.
+
+## Tool catalogue
+
+| Tool                                                          | Class | Purpose                                                 |
+| ------------------------------------------------------------- | ----- | ------------------------------------------------------- |
+| `list_devices`                                                | quick | Enumerate Android + iOS (sim + physical) devices        |
+| `dump_a11y_tree`                                              | long  | Dump UIAutomator XML / XCUITest a11y as structured tree |
+| `wait_for_native_element`                                     | long  | Poll the a11y tree until a finder matches               |
+| `native_tap`                                                  | quick | Tap by coordinates or finder (bounds-center)            |
+| `native_type`                                                 | quick | Type into focused input                                 |
+| `native_swipe`                                                | quick | Swipe between two coordinates                           |
+| `native_back` / `_home` / `_app_switch` / `_open_settings`    | quick | System keys / intents                                   |
+| `native_pin_lock`                                             | quick | Toggle Android lock-task (kiosk mode)                   |
+| `dismiss_permission_dialog`                                   | quick | Smart allow/deny on runtime permission prompt           |
+| `native_permission_grant` / `_deny`                           | quick | `pm grant` / `pm revoke`                                |
+| `take_device_screenshot`                                      | quick | Base64 PNG via image content                            |
+| `set_device_orientation`                                      | quick | Portrait / landscape                                    |
+| `native_clipboard_set` / `_get`                               | quick | Device clipboard                                        |
+| `start_device_logs` / `poll_device_logs` / `stop_device_logs` | quick | Split-tool logcat / oslog tail                          |
+| `solve_oauth_cct`                                             | long  | CCT/SVC OAuth via Playwright + deep-link dispatch       |
+
+All long-running tools are wrapped by the shared `runWithWatchdog` so the 60-second MCP client ceiling never kills them.
+
+## Architecture
+
+Every tool routes shell commands through a `Device` abstraction:
+
+```text
+Tool handler ─► registry.get(deviceId) ─► AndroidDevice  ─► adb -s <udid> ...
+                                       ─► IosSimDevice   ─► xcrun simctl ...
+                                       ─► IosPhysicalDev ─► go-ios       ...
+```
+
+`AndroidDevice` / `IosSimDevice` / `IosPhysicalDevice` all implement the same `DeviceTransport` interface (`shell()`, `upload()`, `download()`, `isAlive()`, `dispose()`). A future remote-device adapter (WSL, SSH) drops in by implementing the same interface — no tool code changes.
+
+```mermaid
+flowchart LR
+    A[Tool handler] --> R[DeviceRegistry]
+    R -->|cached| D[DeviceTransport]
+    D --> Adb[AndroidDevice<br/>adb -s udid]
+    D --> Sim[IosSimDevice<br/>xcrun simctl]
+    D --> Phy[IosPhysicalDevice<br/>go-ios]
+    D -.future.-> Ssh[SshDevice<br/>ssh user@host adb ...]
+    D -.future.-> Wsl[WslDevice<br/>wsl -- adb ...]
+```
+
+## CCT OAuth bypass — `solve_oauth_cct`
+
+Chrome Custom Tabs and SafariViewController hide the OAuth flow behind a system-owned web view that no UI driver can introspect. We do **not** try to drive CCT directly. Instead:
+
+1. Launch Playwright Chromium with the provider's `authorize` URL.
+2. Submit credentials (optional `fillFlow`) — pause for human MFA when needed.
+3. Intercept the redirect to the app scheme (`com.example.myapp://callback?code=…`) before Chromium drops it as `ERR_UNKNOWN_URL_SCHEME`.
+4. Deliver the same URL into the app via `Device.shell()`:
+   - Android: `adb shell am start -W -a android.intent.action.VIEW -d <url>`
+   - iOS Sim: `xcrun simctl openurl <udid> <url>`
+   - iOS physical: requires `idb` (out of scope for this server today).
+
+The Flutter app's deep-link handler cannot distinguish the dispatched intent from a real CCT close — the same `Intent.ACTION_VIEW` arrives with the same URL. PKCE state stays valid because the app initiated the flow (its `code_verifier` is in its own memory).
+
+## Configuration
+
+| Env var                                   | Default      | Purpose                                 |
+| ----------------------------------------- | ------------ | --------------------------------------- |
+| `FLUTTER_ULTRA_ADB`                       | `adb`        | Path to the `adb` binary                |
+| `FLUTTER_ULTRA_XCRUN`                     | `xcrun`      | Path to `xcrun`                         |
+| `FLUTTER_ULTRA_GO_IOS_BIN`                | `ios`        | Path to the go-ios `ios` CLI            |
+| `FLUTTER_ULTRA_TOOL_TIMEOUT_<NAME_UPPER>` | tool default | Override per-tool watchdog ceiling (ms) |
+| `FLUTTER_ULTRA_LOG_LEVEL`                 | `info`       | `debug` / `info` / `warn` / `error`     |
+
+## Platform support
+
+| Tool                                 | Linux             | macOS | Windows                        |
+| ------------------------------------ | ----------------- | ----- | ------------------------------ |
+| Android tools                        | yes (adb on PATH) | yes   | yes                            |
+| iOS Simulator tools                  | no                | yes   | no                             |
+| iOS physical (go-ios)                | yes               | yes   | yes (depends on go-ios binary) |
+| `solve_oauth_cct` (Android dispatch) | yes               | yes   | yes                            |
+| `solve_oauth_cct` (iOS sim dispatch) | no                | yes   | no                             |
+
+iOS tools called on non-darwin hosts return a structured "unsupported" payload (per AC-NM3) — they do not crash the server.
+
+## Acceptance criteria
+
+- **AC-NM1** — `dismiss_permission_dialog(intent='allow')` clears a runtime permission within 3s on the Android emulator.
+- **AC-NM2** — On iOS Simulator (Mac), `native_tap` on a SafariViewController OAuth login button completes the flow combined with `wait_for_url`.
+- **AC-NM3** — iOS tools cleanly return `unsupported` on win32 / linux.
+- **AC-NM4** — `solve_oauth_cct` end-to-end completes an OIDC OAuth flow against your identity provider on Android emulator within 60s.
+
+## Development
+
+```bash
+npm install                                    # at repo root
+npm run -w @flutter-ultra/flutter-ultra-native-mobile build
+npm run -w @flutter-ultra/flutter-ultra-native-mobile test
+```
+
+The unit-test suite focuses on the host-side parsers (`adb devices -l`, UIAutomator XML, simctl JSON) and the `Device` abstraction — full device-loop tests require an attached Android emulator and live in the cross-platform e2e workflow.