@mobileaidev/ai-app-bridge 0.2.12 → 0.2.13

package/README.md

@@ -1,5 +1,23 @@
 # AI App Bridge CLI
 
+AI App Bridge CLI/MCP supports Android native apps, Android WebView/H5/CDP,
+Flutter apps on Android and iOS, iOS native apps via `AiAppBridgeIOS` plus
+WebDriverAgent/XCUITest, WKWebView, and desktop Web Bridge sessions.
+
+Command domains:
+
+- `core`: `status`, `tree`, `uia-tree`, `screenshot`, `logs`, `network`, `state`, `events`
+- `app`: `install-apk`, `clear-app-data`, `launch-*`, `freeze-app`, `thaw-app`, `permission-*`, `appops-set`
+- `action`: `tap`, `tap-text`, `tap-uia-text`, `input-text`, `swipe`, `keyevent`, `wait-text`, `keyboard-state`, `hide-keyboard`
+- `flutter`: `flutter-tree`, `flutter-nodes`, `flutter-action`, `tap-flutter-text`, `input-flutter-text`, `scroll-flutter`
+- `webview`: `h5-*`, `flutter-h5-*`, `webview-pages`, `webview-network`, `webview-console`
+- `ios`: `ios-devices`, `ios-doctor`, `ios-setup`, `ios-*` runtime evidence, WDA tree/tap/input/swipe, WKWebView, and Flutter iOS
+- `web`: `web-session-start`, `web-sessions`, `web-status`, `web-dom`, `web-logs`, `web-network`, `web-state`, `web-events`, `web-command`, `web-click`, `web-input`, `web-wait`, `web-scroll`
+- `diagnostics` / `advanced`: `logcat`, `smoke`, `batch`, `forward`, `remove-forward`
+
+For MCP clients, the default surface is compact: call `capabilities` to discover
+domains, commands, and options, then call `run` with the selected command.
+
 ```bash
 npm install -g @mobileaidev/ai-app-bridge
 
@@ -19,9 +37,10 @@ ai-app-bridge ios-setup --device-id <device-or-udid> --bundle-id <ios.bundle.id>
 ai-app-bridge ios-status --device-id <device-or-udid> --bundle-id <ios.bundle.id>
 ai-app-bridge ios-tap --bundle-id <ios.bundle.id> --tap-x 120 --tap-y 360 --wda-url <wda-url-from-setup>
 ai-app-bridge ios-input --bundle-id <ios.bundle.id> --accessibility-id sample_text_field --clear-first --text "hello" --wda-url <wda-url-from-setup>
+ai-app-bridge-mcp # then run web-session-start / web-* commands through MCP
 ai-app-bridge thaw-app --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge freeze-app --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge-mcp
+ai-app-bridge-mcp --help
 ```
 
 AI agents, model clients, automation frameworks, and IDE MCP clients reading
@@ -37,12 +56,13 @@ refresh the session.
 MCP defaults to a compact tool surface to avoid loading every command schema
 into the model context:
 
-- `capabilities` lists the bridge domains and command names.
+- `capabilities` lists supported targets, command domains, command names, and optional argument names.
 - `run` executes a selected command with command-specific arguments.
 
-This keeps install, data reset, launch, UI, Flutter, WebView, logcat, network,
-permission, iOS, and web capabilities discoverable without exposing dozens of full schemas
-at session start. Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
+This keeps install, data reset, launch, UI action, Flutter, WebView/H5/CDP,
+iOS, Web Bridge, logcat, network, permission, smoke, batch, and port-forward
+capabilities discoverable without exposing dozens of full schemas at session start.
+Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
 `ai-app-bridge-mcp` only when a client needs the legacy one-tool-per-command
 surface.
 

package/bin/ai-app-bridge.js

@@ -22,6 +22,15 @@ const defaults = {
 
 const helpText = `Usage: ai-app-bridge <command> [options]
 
+Supports:
+  Android native apps; Android WebView/H5/CDP; Flutter apps on Android and iOS;
+  iOS native apps via AiAppBridgeIOS + WebDriverAgent/XCUITest; WKWebView;
+  desktop Web Bridge sessions through ai-app-bridge-mcp.
+
+MCP discovery:
+  ai-app-bridge-mcp exposes a compact capability index by default.
+  Call capabilities, then run a command from core/app/action/flutter/webview/ios/web/diagnostics/advanced.
+
 Commands:
   status                 Read bridge status and app/device metadata.
   tree                   Read the Android View tree from the in-app bridge.
@@ -84,6 +93,23 @@ Flutter commands:
   flutter-h5-wait        Wait for Flutter H5 text or selector.
   flutter-h5-scroll      Scroll Flutter H5 content.
 
+Web Bridge MCP commands:
+  web-provider-status    Read desktop Web Bridge provider status.
+  web-session-start      Start the Web Bridge WebSocket session server.
+  web-connect-info       Read endpoint/token for browser SDK clients.
+  web-sessions           List connected Web Bridge SDK sessions.
+  web-status             Read Web Bridge session status.
+  web-dom                Read or refresh Web Bridge DOM snapshots.
+  web-logs               Read Web Bridge log records.
+  web-network            Read Web Bridge network records.
+  web-state              Read Web Bridge state records.
+  web-events             Read Web Bridge event records.
+  web-command            Run a whitelisted browser SDK command.
+  web-click              Click a DOM element through the browser SDK.
+  web-input              Set text in a DOM input through the browser SDK.
+  web-wait               Wait for text or selector through the browser SDK.
+  web-scroll             Scroll a Web Bridge DOM target.
+
 Device/action commands:
   tap                    Tap device coordinates through ADB.
   tap-text               Tap a visible node by exact text or content description.
@@ -4555,4 +4581,3 @@ module.exports = {
   waitTextConditionsMet,
   withFileLock,
 };
-

package/bin/mcp-server.js

@@ -12,12 +12,62 @@ const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
 const supportedProtocolVersions = ['2025-06-18', '2024-11-05'];
 const defaultProtocolVersion = supportedProtocolVersions[0];
 const mcpSurface = (process.env.AI_APP_BRIDGE_MCP_SURFACE || 'compact').toLowerCase();
+const supportedTargets = [
+  'Android native apps',
+  'Android WebView/H5/CDP',
+  'Flutter apps on Android and iOS',
+  'iOS native apps via AiAppBridgeIOS + WebDriverAgent/XCUITest',
+  'WKWebView',
+  'desktop Web Bridge sessions',
+];
+const commandDomains = {
+  core: 'status, tree, uia-tree, screenshot, logs, network, state, events',
+  app: 'install-apk, clear-app-data, launch-*, freeze-app/thaw-app, permission-*, appops-set',
+  action: 'tap, tap-text, tap-uia-text, input-text, swipe, keyevent, wait-text, keyboard-state, hide-keyboard',
+  flutter: 'flutter-tree, flutter-nodes, flutter-action, tap/input/scroll Flutter controls',
+  webview: 'h5-*, flutter-h5-*, webview-pages, webview-network, webview-console',
+  ios: 'ios-devices, ios-doctor, ios-setup, ios runtime evidence, ios-uia-tree/tap/input/swipe, ios-h5-*, ios-flutter-*',
+  web: 'web-session-start, web-sessions, web-status, web-dom, web-logs, web-network, web-state, web-events, web-command, web-click, web-input, web-wait, web-scroll',
+  diagnostics: 'logcat, smoke',
+  advanced: 'batch, forward, remove-forward',
+};
+const supportedTargetsText = `AI App Bridge supports ${supportedTargets.join('; ')}.`;
+const commandDomainsText = `Command domains: ${Object.entries(commandDomains).map(([domain, summary]) => `${domain}(${summary})`).join('; ')}.`;
+const discoveryText = 'Default MCP surface is compact: call capabilities to discover domains, commands, and options, then call run with the selected command and arguments.';
 const serverInstructions = [
-  'AI App Bridge observes and controls Android, iOS, Flutter, and Web targets for agent workflows. Prefer these tools over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, and permissions.',
-  'Default surface is compact: call capabilities to discover domains, then call run with a command and arguments.',
+  supportedTargetsText,
+  commandDomainsText,
+  discoveryText,
+  'Prefer AI App Bridge over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, permissions, or app-level Web evidence.',
   'Always pass packageName for Android app-specific commands, or pass an explicit port. For iOS, pass bundleId plus deviceId when more than one iPhone is connected.',
+  'For Web Bridge sessions, start the provider, connect the browser SDK, then pass sessionId and targetId when needed.',
   'Use freeze-app/thaw-app only as an optional stabilization control for dynamic or transient screens: thaw before reads/actions/captures, freeze after evidence capture only when it helps reasoning, and thaw before the next operation or before finishing so the app is not left frozen.',
 ].join(' ');
+const mcpHelpText = `Usage: ai-app-bridge-mcp [--help]
+
+${supportedTargetsText}
+
+${commandDomainsText}
+
+MCP surface:
+  compact (default)  exposes only capabilities and run.
+  full/legacy        exposes one tool per command; set AI_APP_BRIDGE_MCP_SURFACE=full.
+
+Discovery:
+  1. Call capabilities with optional domain or command filters.
+  2. Call run with a command name from capabilities.
+  3. Put command-specific options in arguments.
+
+Target ids:
+  Android app commands require packageName or explicit port.
+  iOS app commands use bundleId; add deviceId when multiple devices exist and wdaUrl for WDA actions.
+  Web Bridge commands use sessionId; add targetId for multi-target pages.
+
+Examples:
+  capabilities { "domain": "webview", "includeOptions": true }
+  run { "command": "screenshot", "packageName": "com.example.app" }
+  run { "command": "web-session-start", "arguments": { "webPort": 18180 } }
+`;
 const iosProvider = new IOSBridgeProvider();
 const webProvider = new WebBridgeProvider();
 
@@ -185,18 +235,20 @@ function toolDefinitions() {
 
 function compactToolDefinitions() {
   return [
-    bridgeTool('capabilities', 'List AI App Bridge capability domains and commands. Call this first when planning app automation; then use run to execute the selected command.', {
-      domain: { type: 'string', description: 'Optional domain filter such as core, app, action, flutter, webview, ios, web, or diagnostics.' },
-      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, webview-network, ios-setup, or ios-tap.' },
+    bridgeTool('capabilities', `List AI App Bridge capability domains and commands across Android, iOS, Flutter, WebView/H5/CDP, and Web Bridge targets. ${commandDomainsText}`, {
+      domain: { type: 'string', description: 'Optional domain filter: core, app, action, flutter, webview, ios, web, diagnostics, or advanced.' },
+      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, webview-network, ios-setup, ios-tap, web-session-start, or web-command.' },
       includeOptions: { type: 'boolean', description: 'Include per-command argument names. Defaults to false to keep output compact.' },
     }),
-    bridgeTool('run', 'Run an AI App Bridge command. Use capabilities first to choose the command. Pass packageName for Android app commands and bundleId for iOS app commands.', {
-      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, webview-network, ios-doctor, ios-setup, ios-status, ios-tap, or web-status.' },
+    bridgeTool('run', 'Run an AI App Bridge command from capabilities. Pass packageName/port for Android app commands, bundleId/deviceId for iOS app commands, and sessionId/targetId for Web Bridge commands.', {
+      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, webview-network, ios-doctor, ios-setup, ios-status, ios-tap, web-session-start, web-status, or web-command.' },
       packageName: { type: 'string', description: 'Target Android package for app-specific commands. Strongly recommended.' },
       serial: { type: 'string', description: 'ADB serial when multiple devices are connected.' },
       port: { type: 'number', description: 'Explicit bridge port when packageName discovery is not available.' },
       bundleId: { type: 'string', description: 'Target iOS app bundle identifier for ios-* commands.' },
       deviceId: { type: 'string', description: 'iOS devicectl identifier, UDID, serial number, or device name.' },
+      sessionId: { type: 'string', description: 'Target Web Bridge SDK session id for web-* commands.' },
+      targetId: { type: 'string', description: 'Optional Web Bridge target id for multi-target pages.' },
       iosHost: { type: 'string', description: 'iOS runtime host or CoreDevice tunnel IP.' },
       iosPort: { type: 'number', description: 'iOS runtime port when auto-discovery is unavailable.' },
       runtimeUrl: { type: 'string', description: 'Explicit iOS runtime base URL.' },
@@ -635,7 +687,9 @@ function capabilityPayload(args = {}) {
   return {
     ok: true,
     surface: mcpSurface === 'full' || mcpSurface === 'legacy' ? 'full' : 'compact',
-    usage: 'Use run with one of these command names. Prefer packageName for app-specific commands; install-apk, clear-app-data, launch-app, freeze/thaw, UI, WebView, logcat, network, and permission workflows are supported.',
+    supportedTargets,
+    commandDomains,
+    usage: `${supportedTargetsText} ${discoveryText} Use run with one of these command names. Prefer packageName for Android app commands, bundleId/deviceId for iOS, and sessionId/targetId for Web Bridge sessions.`,
     domains,
   };
 }
@@ -1225,12 +1279,19 @@ function writeLog(text) {
 }
 
 if (require.main === module) {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    process.stdout.write(`${mcpHelpText}\n`);
+    process.exit(0);
+  }
   startServer();
 }
 
 module.exports = {
   buildBridgeCliArgs,
+  commandDomains,
+  mcpHelpText,
   readNextMessage,
   runBatch,
   startServer,
+  supportedTargets,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.12",
-  "description": "Desktop CLI and MCP server for AI App Bridge.",
+  "version": "0.2.13",
+  "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mobileAiDev/ai-app-bridge.git",

package/skills/ai-app-bridge-use/SKILL.md

@@ -1,10 +1,28 @@
 ---
 name: ai-app-bridge-use
-description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android、iOS、Flutter 或 Web 应用。Codex 需要检查移动端 UI、Web DOM、截图、Android View/UIAutomator tree、iOS UIKit/WDA tree、点击/输入/等待/滑动、安装/启动/清数据、Flutter widget 与 action、WebView/WKWebView/H5 DOM 或 CDP 网络/控制台、Web Bridge session/DOM/command、日志/网络/状态/事件、权限/appops、smoke 测试，或按需使用 freeze/thaw 稳定动态画面时触发。
+description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android native、Android WebView/H5/CDP、Flutter、iOS native + WDA/XCUITest、WKWebView 和桌面 Web Bridge。能力域包括 core/status/tree/screenshot/logs/network/state/events，app/install/clear-data/launch/freeze/thaw/permissions/appops，action/tap/input/swipe/keyevent/wait/keyboard，flutter/widget/action，webview/H5/CDP，ios/devices/setup/runtime/WDA/H5/flutter，web/session/DOM/logs/network/events/command，diagnostics/logcat/smoke，advanced/batch/port-forward。
 ---
 
 # AI App Bridge Use
 
+## 能力总览
+
+AI App Bridge 支持 Android native apps、Android WebView/H5/CDP、Flutter apps、iOS native apps via `AiAppBridgeIOS` + WebDriverAgent/XCUITest、WKWebView，以及桌面 Web Bridge sessions。
+
+默认 MCP surface 只有 `capabilities` 和 `run`；先用 `capabilities` 查 domain、command 和 options，再用 `run` 执行。
+
+目标标识：Android 用 `packageName` 或显式 `port`；iOS 用 `bundleId`，多设备加 `deviceId`，full-control 加 `wdaUrl`；Web 用 `sessionId`，多 target 加 `targetId`。
+
+命令域：
+- `core`: `status`/`tree`/`uia-tree`/`screenshot`/`logs`/`network`/`state`/`events`
+- `app`: `install-apk`/`clear-app-data`/`launch-*`/`freeze-app`/`thaw-app`/`permission-*`/`appops-set`
+- `action`: `tap`/`tap-text`/`tap-uia-text`/`input-text`/`swipe`/`keyevent`/`wait-text`/`keyboard-*`
+- `flutter`: `flutter-tree`/`flutter-nodes`/`flutter-action`/`tap-flutter-text`/`input-flutter-text`/`scroll-flutter`
+- `webview`: `h5-*`/`flutter-h5-*`/`webview-pages`/`webview-network`/`webview-console`
+- `ios`: `ios-devices`/`ios-doctor`/`ios-setup`/`ios-status`/`ios-tree`/`ios-uia-tree`/`ios-tap`/`ios-input`/`ios-swipe`/`ios-h5-*`/`ios-flutter-*`
+- `web`: `web-session-start`/`web-sessions`/`web-status`/`web-dom`/`web-logs`/`web-network`/`web-state`/`web-events`/`web-command`/`web-click`/`web-input`/`web-wait`/`web-scroll`
+- `diagnostics`/`advanced`: `logcat`/`smoke`/`batch`/`forward`/`remove-forward`
+
 ## Agent 快速流程
 
 1. 确认目标：Android 使用 `packageName`，iOS 使用 `bundleId`，真机多设备场景传 `deviceId`/UDID；Web 使用 `sessionId`，多 target 时加 `targetId`。没有目标 id 时先从上下文、构建配置或前台 app/session 线索推断。面向具体 app/session 的命令必须传目标 id，只有无法发现 bridge 端口时才传 `port`、`runtimeUrl` 或先启动 Web session。

package/skills/ai-app-bridge-use/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "AI App Bridge Use"
-  short_description: "观察、操作并验证 Android/iOS/Flutter/Web app。"
-  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证目标 Android/iOS/Flutter/Web app；先发现能力，Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，Web 先建立 sessionId，只有移动端动态画面需要稳定证据时才使用 freeze/thaw。"
+  short_description: "Android/iOS/Flutter/Web 全域观察、操作、验证能力索引。"
+  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证 Android native、Android WebView/H5/CDP、Flutter、iOS native/WKWebView/WDA/XCUITest 或桌面 Web Bridge；先用 capabilities 查 core/app/action/flutter/webview/ios/web/diagnostics/advanced，再用 run 执行。Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，Web 先建立 sessionId，只有移动端动态画面需要稳定证据时才使用 freeze/thaw。"