@bdayadev/flutter-ultra-mcp 0.0.0

package/packages/flutter-ultra-browser/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flutter-ultra/flutter-ultra-browser",
+  "version": "0.0.0",
+  "private": true,
+  "description": "MCP server for Playwright-driven browser automation: OAuth redirects, popups, console capture, network, sandboxed JS.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-browser": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "playwright-core": "^1.49.0",
+    "proper-lockfile": "^4.1.2",
+    "superjson": "^2.2.1",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "devDependencies": {
+    "@types/proper-lockfile": "^4.1.4",
+    "playwright": "^1.49.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  }
+}

package/packages/flutter-ultra-build/README.md

@@ -0,0 +1,60 @@
+# @flutter-ultra/flutter-ultra-build
+
+MCP server for Flutter **build-time** tasks: pubspec, codegen, analyze, format, tests, builds, signing, l10n, assets, web validators.
+
+Part of the [flutter-ultra-mcp](https://github.com/Bdaya-Dev/flutter-ultra-mcp) plugin (8 specialized MCP servers for Flutter automation). This package focuses on _build-time_ surface area — it never connects to a running app. For runtime control (hot reload, widget inspection) see `@flutter-ultra/flutter-ultra-runtime`.
+
+## Tool groups (~50 tools)
+
+| Group             | Representative tools                                                                                                                                                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Project meta      | `list_projects`, `project_info`, `list_flavors`, `list_dart_defines`                                                                                                                                                                                   |
+| Analysis & format | `analyze`, `format`, `fix`, `fix_preview`, `flutter_doctor`, `flutter_clean`, `pub_cache_repair`                                                                                                                                                       |
+| Pubspec & deps    | `pub_get`, `pub_add`, `pub_remove`, `pub_upgrade`, `pub_outdated`, `pub_deps`, `pub_dev_search`, `pubspec_overrides_*`, `start_pub_upgrade_major` (+ poll / get / cancel)                                                                              |
+| Codegen           | `start_build_runner_build` (+ poll / get / cancel), `start_build_runner_watch` (+ poll / stop), `flutter_gen_l10n`                                                                                                                                     |
+| Tests             | `start_run_unit_tests`, `start_run_widget_tests`, `start_run_integration_tests`, `start_run_golden_tests`, `start_update_goldens` (each + poll / get / cancel), `test_filter`                                                                          |
+| Builds            | `start_build_apk` / `start_build_appbundle` / `start_build_ipa` (Mac) / `start_build_web` / `start_build_windows` (Win) / `start_build_macos` (Mac) / `start_build_linux` (Linux), each with `poll_build_<plat>_job` / `get_*_result` / `cancel_*_job` |
+| Mobile signing    | `verify_android_signing`, `verify_ios_signing` (Mac-only), `set_bundle_id` (atomic Android+iOS update)                                                                                                                                                 |
+| l10n / ARB        | `list_missing_translations`, `arb_diff`, `arb_add_key`, `arb_remove_key`                                                                                                                                                                               |
+| Assets            | `add_asset`, `validate_assets`, `list_orphan_assets`                                                                                                                                                                                                   |
+| Web pre-flight    | `validate_web_redirect`, `validate_canvaskit_vs_html_consistency`, `flush_service_worker`                                                                                                                                                              |
+
+All long-running tools (builds, codegen, tests, pub-upgrade-major) follow the **MARATHON split-tool pattern** documented in the plan §17.5: each exposes a `start_<x>` / `poll_<x>_job` / `get_<x>_result` / `cancel_<x>_job` quartet so no sync MCP call ever exceeds 55 s. Job state persists at `${CLAUDE_PLUGIN_DATA}/state/jobs/<jobId>.json` and survives MCP server restarts.
+
+## Cross-cutting behavior
+
+- **Watchdog**: every tool wrapped in `withWatchdog` with a per-tool ceiling. Host-side cancellation propagates to child processes via `SIGTERM` → 2 s grace → `SIGKILL`.
+- **Logging**: stderr only, JSON-lines, respects `FLUTTER_ULTRA_LOG_LEVEL`. Stdout reserved for JSON-RPC framing.
+- **Keep-alive**: 30 s `notifications/message` (debug) defeats the Bun-idle-SIGKILL bug ([claude-code #58004](https://github.com/anthropics/claude-code/issues/58004)).
+- **Per-tool timeout overrides**: `FLUTTER_ULTRA_TOOL_TIMEOUT_<TOOL_NAME>=<ms>` env var raises the ceiling for power users.
+
+## CLI dependencies
+
+Tools shell out to:
+
+- `dart` (required) — analysis, format, fix, pub, build_runner
+- `flutter` (required for any Flutter-specific tool) — pub, gen-l10n, test, build
+- `keytool` (optional, for `verify_android_signing`)
+- `xcodebuild` (Mac-only, for `verify_ios_signing`)
+
+Resolution order: env override (`FLUTTER_ULTRA_DART_BIN`, `FLUTTER_ULTRA_FLUTTER_BIN`) → PATH lookup. Missing CLIs raise `FlutterCliMissingError` with install hints.
+
+## Running standalone
+
+```jsonc
+// .claude/mcp.json
+{
+  "mcpServers": {
+    "flutter-ultra-build": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/flutter-ultra-build/dist/index.js"],
+    },
+  },
+}
+```
+
+## References
+
+- Plan §5.1 — tool catalogue (build server)
+- Plan §16 — naming, schema, output conventions (binding for all servers)
+- Plan §17 — timeout resilience model + split-tool pattern (binding)

package/packages/flutter-ultra-build/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flutter-ultra/flutter-ultra-build",
+  "version": "0.0.0",
+  "private": true,
+  "description": "MCP server for Flutter build-time tasks: pubspec, codegen, analyze, format, tests, builds, l10n, assets.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-build": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "execa": "^9.5.1",
+    "fs-extra": "^11.2.0",
+    "nanoid": "^5.0.9",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.6.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/proper-lockfile": "^4.1.4",
+    "vitest": "^2.1.9"
+  }
+}

package/packages/flutter-ultra-devtools/README.md

@@ -0,0 +1,7 @@
+# @flutter-ultra/flutter-ultra-devtools
+
+MCP server backing the **DevTools panel**: live MCP activity, attached sessions, recent tool calls, errors, screenshot grid. Tails `state/tool-events.jsonl` and pushes via WebSocket to the panel iframe.
+
+**Status:** scaffold stub. Implementation owner: **wave-2 devtools worker** (see plan §12).
+
+Pairs with the `ultra_flutter_devtools` Dart package (the DevTools extension UI) — see `packages/ultra_flutter_devtools/`.

package/packages/flutter-ultra-devtools/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@flutter-ultra/flutter-ultra-devtools",
+  "version": "0.0.0",
+  "private": true,
+  "description": "MCP server backing the Flutter DevTools panel: live MCP activity, sessions, tool-call timeline.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-devtools": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@flutter-ultra/mcp-runtime": "*",
+    "@flutter-ultra/state-store": "*",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  }
+}

package/packages/flutter-ultra-gesture/README.md

@@ -0,0 +1,51 @@
+# @flutter-ultra/flutter-ultra-gesture
+
+MCP server for **gesture dispatch** inside a running Flutter app via the in-app `ultra_flutter` mixin. Tools call `ext.flutter.ultra.*` service extensions registered by `UltraFlutterBinding` in the target app, so the app must include `package:ultra_flutter` and register the binding for any tool here to work.
+
+## Prerequisites
+
+- A Flutter app running in `--debug` mode with `package:ultra_flutter` ≥ 0.0.1 registered as a binding mixin.
+- The runtime server (`@flutter-ultra/flutter-ultra-runtime`) attached to the session — it owns session discovery and publishes `state/sessions.json` + `state/session-<id>.json`. This server is a read-only consumer of that state.
+
+## Tool catalogue (17)
+
+| Tool                                   | Maps to                                                                                                                                                         |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `interactive_elements`                 | `ext.flutter.ultra.interactiveElements` (rev-23 tightened: no truncation by default, optional pagination, sortBy, `withinSubtree` + `kinds` + `hasKey` filters) |
+| `tap` / `double_tap` / `long_press`    | `ext.flutter.ultra.tap` / `.doubleTap` / `.longPress`                                                                                                           |
+| `enter_text` / `clear_text`            | `ext.flutter.ultra.enterText` / `.clearText`                                                                                                                    |
+| `swipe` / `pinch_zoom`                 | `ext.flutter.ultra.swipe` / `.pinchZoom`                                                                                                                        |
+| `scroll_to` / `scroll_until_visible`   | `ext.flutter.ultra.scrollTo` (server-side polling for `scroll_until_visible`)                                                                                   |
+| `take_screenshots`                     | `ext.flutter.ultra.takeScreenshots`                                                                                                                             |
+| `take_responsive_screenshots`          | Delegates: web → `flutter-ultra-browser` (CDP `setDeviceMetricsOverride`); native → single-viewport fallback w/ `nativeMultiViewportUnavailable` warning        |
+| `start_screencast` / `stop_screencast` | `ext.flutter.ultra.startScreencast` / `.stopScreencast`                                                                                                         |
+| `call_custom_extension`                | invokes any user-registered `registerUltraExtension(name, ...)`                                                                                                 |
+| `list_custom_extensions`               | `ext.flutter.ultra.listExtensions`                                                                                                                              |
+| `wait_for`                             | server-side polling: `interactiveElements` every 200ms with finder match                                                                                        |
+
+## Finder spec
+
+All matcher-accepting tools share `FinderSpec` (Zod discriminated union):
+
+```ts
+{ kind: 'key',     value: string }
+{ kind: 'text',    value: string, matchType?: 'exact' | 'contains' | 'regex' }  // default 'exact'
+{ kind: 'type',    value: string }
+{ kind: 'coords',  x: number, y: number }
+{ kind: 'focused' }
+{ kind: 'tooltip', value: string }     // server-side filter via interactiveElements
+{ kind: 'semantics', label: string, matchType?: 'exact' | 'contains' }  // server-side filter
+{ kind: 'descendant', of: FinderSpec, matching: FinderSpec }            // server-side filter
+```
+
+Server-side filters (`tooltip`/`semantics`/`descendant`) materialise the element list via `interactive_elements`, resolve a coordinate, then issue `ext.flutter.ultra.tap` with `{x, y}`. Native finders (`key`/`text`/`type`/`coords`/`focused`) call the extension directly.
+
+## Configuration
+
+Reads `state/sessions.json` and `state/session-<id>.json` written by `flutter-ultra-runtime`. Override the state directory with `FLUTTER_ULTRA_STATE_DIR` (defaults to `${FLUTTER_ULTRA_DATA:-~/.flutter-ultra-mcp}/state`).
+
+DDS client name is `flutter-ultra/gesture/<pid>` so this server identifies as a distinct DDS client from the runtime server (per plan §7.2).
+
+## Coordination
+
+This server **never writes** to `sessions.json`. Session lifecycle is owned by `flutter-ultra-runtime`. We open our own VM-service WebSocket per session and cache one `VmServiceClient` per active session id. The cache is dropped when the runtime server marks the session `terminated`.

package/packages/flutter-ultra-gesture/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@flutter-ultra/flutter-ultra-gesture",
+  "version": "0.0.1",
+  "private": false,
+  "description": "MCP server for in-app gesture dispatch via the ultra_flutter mixin: tap, text entry, scroll, screenshot, screencast.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/packages/flutter-ultra-gesture",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "packages/flutter-ultra-gesture"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "flutter",
+    "mcp",
+    "ultra_flutter",
+    "gesture",
+    "tap",
+    "screencast"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-gesture": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@flutter-ultra/vm-service-client": "^0.0.1",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +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).

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

@@ -0,0 +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"
+  }
+}

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

@@ -0,0 +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.