@mobileaidev/ai-app-bridge 0.2.0 → 0.2.2

package/README.md

@@ -4,15 +4,29 @@
 npm install -g @mobileaidev/ai-app-bridge
 
 ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge install-apk --package-name io.github.mobileaidev.aiappbridge.sample --apk-path app-debug.apk
-ai-app-bridge screenshot --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge install-apk --package-name io.github.mobileaidev.aiappbridge.sample --apk-path app-debug.apk
+ai-app-bridge launch-app --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge launch-activity --package-name io.github.mobileaidev.aiappbridge.sample --activity .MainActivity --extra route=/home
+ai-app-bridge screenshot --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge input-text --package-name io.github.mobileaidev.aiappbridge.sample --text "中文输入" --hide-keyboard
 ai-app-bridge network --package-name io.github.mobileaidev.aiappbridge.sample --compact --url-filter /api/
-ai-app-bridge webview-network --package-name io.github.mobileaidev.aiappbridge.sample --duration-ms 3000
-ai-app-bridge-mcp
-```
-
+ai-app-bridge webview-network --package-name io.github.mobileaidev.aiappbridge.sample --duration-ms 3000
+ai-app-bridge-mcp
+```
+
+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.
+- `run` executes a selected command with command-specific arguments.
+
+This keeps install, launch, UI, Flutter, WebView, logcat, network, and
+permission 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.
+
 WebView network and console capture use Android WebView DevTools/CDP when the
 target app is debuggable and WebView debugging is enabled.
 
@@ -25,5 +39,11 @@ When `screenshot` or `smoke` runs without `--out-file`, the CLI writes a unique
 PNG under `build/ai_app_bridge_artifacts` instead of reusing a stable filename
 or creating files in the project root.
 It keeps the newest 20 generated screenshots for each command prefix. Use
-`--artifact-dir` to choose that directory, or `--out-file` when a fixed path is
-intentional.
+`--artifact-dir` to choose that directory, or `--out-file` when a fixed path is
+intentional.
+
+`launch-app` queries Android LAUNCHER activities before starting the app. If a
+debug dependency exposes multiple launcher entries, it returns
+`launcher_ambiguous` with the candidates instead of guessing. Use
+`launch-activity` or `launch-app --activity/--component` to choose the intended
+entry point explicitly.

package/bin/ai-app-bridge.js

@@ -68,10 +68,12 @@ Device/action commands:
   keyboard-state         Read Android soft keyboard visibility from dumpsys.
   hide-keyboard          Hide the Android soft keyboard when it is visible.
 
-App/permission commands:
-  install-apk            Install an APK and assist device-side installer screens.
-  launch-native-test     Launch the debug native Android bridge test Activity.
-  launch-flutter         Launch the Flutter Activity.
+App/permission commands:
+  install-apk            Install an APK and assist device-side installer screens.
+  launch-app             Launch the target package LAUNCHER Activity.
+  launch-activity        Launch an explicit Android Activity component.
+  launch-native-test     Launch the debug native Android bridge test Activity.
+  launch-flutter         Launch the Flutter Activity.
   permission-state       Read Android runtime permission state.
   permission-grant       Grant an Android runtime permission.
   permission-revoke      Revoke an Android runtime permission.
@@ -92,7 +94,13 @@ Options:
   --adb-timeout-ms <ms>  Timeout for ADB subprocesses.
   --out-file <path>      Screenshot output path.
   --artifact-dir <path>  Directory for generated screenshot/artifact defaults.
-  --apk-path <path>      APK path used by install-apk.
+  --apk-path <path>      APK path used by install-apk.
+  --activity <name>      Activity class for launch-activity or launch-app override.
+  --component <pkg/act>  Explicit Android component for launch-activity.
+  --action <name>        Intent action for launch-activity.
+  --category <name>      Intent category for launch-activity; may be repeated.
+  --data <uri>           Intent data URI for launch-activity.
+  --extra <key=value>    String intent extra for launch-activity; may be repeated.
   --text <text>          Text used by Unicode-safe bridge input commands.
   --value <text>         Text value used by h5-input or flutter-h5-input.
   --selector <css>       CSS selector used by H5 commands.
@@ -319,11 +327,15 @@ async function runCommand(command, options, ctx) {
       return appopsSet(ctx, requiredString(options.op, 'op'), requiredString(options.mode, 'mode'));
     case 'tap-uia-text':
       return tapUiaText(ctx, requiredString(options.targetText, 'targetText'), options);
-    case 'permission-dialog':
-      return permissionDialog(ctx, options);
-    case 'launch-native-test':
-      return launchNativeTest(ctx);
-    case 'launch-flutter':
+    case 'permission-dialog':
+      return permissionDialog(ctx, options);
+    case 'launch-app':
+      return launchApp(ctx, options);
+    case 'launch-activity':
+      return launchActivity(ctx, options);
+    case 'launch-native-test':
+      return launchNativeTest(ctx);
+    case 'launch-flutter':
       return launchFlutter(ctx, options.initialRoute || '');
     case 'smoke':
       return smoke(ctx, options);
@@ -347,16 +359,25 @@ function parseArgs(argv) {
     const rawName = arg.slice(2);
     const name = rawName.replace(/-([a-z])/g, (_, value) => value.toUpperCase());
     const next = argv[index + 1];
-    if (next === undefined || next.startsWith('--')) {
-      options[name] = true;
-      continue;
-    }
-    options[name] = next;
-    index += 1;
-  }
-  return { command, options };
-}
-
+    if (next === undefined || next.startsWith('--')) {
+      appendOption(options, name, true);
+      continue;
+    }
+    appendOption(options, name, next);
+    index += 1;
+  }
+  return { command, options };
+}
+
+function appendOption(options, name, value) {
+  if (name === 'extra' || name === 'category') {
+    if (!Array.isArray(options[name])) options[name] = [];
+    options[name].push(value);
+    return;
+  }
+  options[name] = value;
+}
+
 async function adb(ctx, args, { binary = false } = {}) {
   const allArgs = adbArgs(ctx, args);
   return new Promise((resolve, reject) => {
@@ -3664,13 +3685,17 @@ async function resolveLogcatPid(ctx, options) {
   return '';
 }
 
-function filterLogcat(text, options) {
-  const tags = splitCsv(options.tag || options.tags);
-  const grep = options.grep ? String(options.grep) : '';
-  const grepCaseSensitive = Boolean(options.grepCaseSensitive);
-  const minLevel = priorityValue(options.level || options.minLevel || '');
-  const pid = options.pid ? String(options.pid) : '';
-  const lines = String(text || '').split(/\r?\n/);
+function filterLogcat(text, options) {
+  const tags = splitCsv(options.tag || options.tags);
+  const grep = options.grep ? String(options.grep) : '';
+  const grepCaseSensitive = Boolean(options.grepCaseSensitive);
+  const minLevel = priorityValue(options.level || options.minLevel || '');
+  const pid = options.pid ? String(options.pid) : '';
+  const requiresAppPid = options.appPid || options.packagePid || options.pid === 'current';
+  if (requiresAppPid && !pid) {
+    return '';
+  }
+  const lines = String(text || '').split(/\r?\n/);
   const filtered = [];
   let previousIncluded = false;
   for (const line of lines) {
@@ -3753,19 +3778,134 @@ function adbFollow(ctx, args, durationMs) {
   });
 }
 
-async function launchNativeTest(ctx) {
-  const component = `${ctx.packageName}/${ctx.nativeActivity}`;
-  await adb(ctx, ['shell', 'am', 'start', '-n', component]);
-  return { ok: true, transport: 'adb', component };
-}
-
-async function launchFlutter(ctx, initialRoute) {
-  const component = `${ctx.packageName}/${ctx.flutterActivity}`;
-  const args = ['shell', 'am', 'start', '-n', component];
-  if (initialRoute) args.push('-e', 'ai_app_initial_route', initialRoute);
-  await adb(ctx, args);
-  return { ok: true, transport: 'adb', component, initialRoute };
-}
+async function launchApp(ctx, options = {}) {
+  if (options.component || options.activity) {
+    return launchActivity(ctx, options);
+  }
+
+  const candidates = await launcherActivityCandidates(ctx);
+  if (candidates.length === 0) {
+    return {
+      ok: false,
+      error: 'launcher_not_found',
+      packageName: ctx.packageName,
+      launcherCandidates: candidates,
+    };
+  }
+  if (candidates.length > 1) {
+    return {
+      ok: false,
+      error: 'launcher_ambiguous',
+      packageName: ctx.packageName,
+      launcherCandidates: candidates,
+      suggestion: 'Pass --component or --activity to choose the intended launcher Activity.',
+    };
+  }
+
+  return startActivity(ctx, candidates[0], options, {
+    packageName: ctx.packageName,
+    launcherCandidates: candidates,
+  });
+}
+
+async function launchActivity(ctx, options = {}) {
+  const component = normalizeActivityComponent(
+    ctx.packageName,
+    options.component || requiredString(options.activity, 'activity'),
+  );
+  return startActivity(ctx, component, options, { packageName: ctx.packageName });
+}
+
+async function launchNativeTest(ctx) {
+  const component = normalizeActivityComponent(ctx.packageName, ctx.nativeActivity);
+  return startActivity(ctx, component, {}, { packageName: ctx.packageName });
+}
+
+async function launchFlutter(ctx, initialRoute) {
+  const component = normalizeActivityComponent(ctx.packageName, ctx.flutterActivity);
+  const options = initialRoute ? { extra: [`ai_app_initial_route=${initialRoute}`] } : {};
+  const result = await startActivity(ctx, component, options, { packageName: ctx.packageName });
+  return { ...result, initialRoute };
+}
+
+async function launcherActivityCandidates(ctx) {
+  const result = await adb(ctx, [
+    'shell',
+    'cmd',
+    'package',
+    'query-activities',
+    '--brief',
+    '-a',
+    'android.intent.action.MAIN',
+    '-c',
+    'android.intent.category.LAUNCHER',
+    ctx.packageName,
+  ]);
+  return parseLauncherActivityCandidates(result.stdout);
+}
+
+function parseLauncherActivityCandidates(stdout) {
+  const candidates = [];
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    const candidate = line.trim();
+    if (/^[A-Za-z0-9_.$]+\/[A-Za-z0-9_.$]+$/.test(candidate) && !candidates.includes(candidate)) {
+      candidates.push(candidate);
+    }
+  }
+  return candidates;
+}
+
+function normalizeActivityComponent(packageName, activityOrComponent) {
+  const value = requiredString(activityOrComponent, 'activity');
+  if (value.includes('/')) return value;
+  return `${packageName}/${value}`;
+}
+
+async function startActivity(ctx, component, options = {}, extraResult = {}) {
+  const args = buildAmStartArgs(component, options);
+  const result = await adb(ctx, args);
+  return {
+    ok: true,
+    transport: 'adb',
+    component,
+    ...extraResult,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+  };
+}
+
+function buildAmStartArgs(component, options = {}) {
+  const args = ['shell', 'am', 'start'];
+  if (options.action) args.push('-a', options.action);
+  for (const category of optionList(options.category)) {
+    args.push('-c', category);
+  }
+  if (options.data) args.push('-d', options.data);
+  for (const extra of parseStartExtras(options.extra)) {
+    args.push('-e', extra.key, extra.value);
+  }
+  args.push('-n', component);
+  return args;
+}
+
+function parseStartExtras(rawExtras) {
+  return optionList(rawExtras).map((rawExtra) => {
+    const value = String(rawExtra);
+    const separator = value.indexOf('=');
+    if (separator <= 0) {
+      throw new Error('extra must use key=value');
+    }
+    return {
+      key: value.slice(0, separator),
+      value: value.slice(separator + 1),
+    };
+  });
+}
+
+function optionList(value) {
+  if (value === undefined || value === null || value === false || value === '') return [];
+  return Array.isArray(value) ? value : [value];
+}
 
 async function smoke(ctx, options) {
   const summary = {
@@ -4131,9 +4271,10 @@ module.exports = {
   compactUiaTree,
   defaultArtifactDirectory,
   defaultArtifactPath,
-  findFlutterNode,
-  findTappableNodeByText,
-  firstErrorLine,
+  findFlutterNode,
+  findTappableNodeByText,
+  filterLogcat,
+  firstErrorLine,
   flutterNodePoint,
   flutterPhysicalViewport,
   helpText,
@@ -4141,10 +4282,14 @@ module.exports = {
   isAdbInputTextSafe,
   isLikelyInstallerSurface,
   nodeTapState,
-  normalizeBridgeError,
-  parseWebViewDevToolsSockets,
-  parseKeyboardState,
-  parseUiaBounds,
+  normalizeBridgeError,
+  normalizeActivityComponent,
+  parseWebViewDevToolsSockets,
+  parseArgs,
+  parseKeyboardState,
+  parseLauncherActivityCandidates,
+  parseStartExtras,
+  parseUiaBounds,
   parseUiaViewport,
   parseComponentFromWindowLine,
   parseForegroundWindow,

package/bin/mcp-server.js

@@ -4,11 +4,19 @@ const { spawn } = require('child_process');
 const path = require('path');
 
 const packageInfo = require('../package.json');
-const bridgeDir = __dirname;
-const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
-const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
-
-let buffer = Buffer.alloc(0);
+const bridgeDir = __dirname;
+const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
+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 serverInstructions = [
+  'AI App Bridge observes and controls Android apps for agent workflows. Prefer these tools over raw adb when inspecting UI, text, WebView, logs, network, app install, launch, and permissions.',
+  'Default surface is compact: call capabilities to discover domains, then call run with a command and arguments.',
+  'Always pass packageName for app-specific commands, or pass an explicit port. Do not rely on a sample/default package in MCP sessions.',
+].join(' ');
+
+let buffer = Buffer.alloc(0);
 
 process.stdin.on('data', (chunk) => {
   buffer = Buffer.concat([buffer, chunk]);
@@ -70,20 +78,27 @@ async function handleMessage(body) {
   }
 
   try {
-    if (message.method === 'initialize') {
-      sendResult(message.id, {
-        protocolVersion: message.params?.protocolVersion || '2024-11-05',
-        capabilities: {
-          tools: {},
-        },
-        serverInfo: {
-          name: 'ai-app-bridge',
-          version: packageInfo.version,
-        },
-      });
-      return;
-    }
-
+    if (message.method === 'initialize') {
+      sendResult(message.id, {
+        protocolVersion: negotiateProtocolVersion(message.params?.protocolVersion),
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'ai-app-bridge',
+          title: 'AI App Bridge',
+          version: packageInfo.version,
+        },
+        instructions: serverInstructions,
+      });
+      return;
+    }
+
+    if (message.method === 'ping') {
+      sendResult(message.id, {});
+      return;
+    }
+
     if (message.method === 'tools/list') {
       sendResult(message.id, { tools: toolDefinitions() });
       return;
@@ -101,10 +116,46 @@ async function handleMessage(body) {
   } catch (error) {
     sendError(message.id, -32000, error.message || String(error));
   }
-}
-
-function toolDefinitions() {
-  return [
+}
+
+function negotiateProtocolVersion(requestedVersion) {
+  if (supportedProtocolVersions.includes(requestedVersion)) {
+    return requestedVersion;
+  }
+  return defaultProtocolVersion;
+}
+
+function toolDefinitions() {
+  if (mcpSurface === 'full' || mcpSurface === 'legacy') {
+    return fullToolDefinitions();
+  }
+  return compactToolDefinitions();
+}
+
+function compactToolDefinitions() {
+  return [
+    bridgeTool('capabilities', 'List AI App Bridge capability domains and commands. Call this first when planning Android app automation; then use run to execute the selected command.', {
+      domain: { type: 'string', description: 'Optional domain filter such as core, app, action, flutter, webview, or diagnostics.' },
+      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, or webview-network.' },
+      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. Always pass packageName for app-specific commands.', {
+      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, tree, webview-network, or logcat.' },
+      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.' },
+      adb: { type: 'string', description: 'ADB executable path or command.' },
+      arguments: {
+        type: 'object',
+        description: 'Command-specific arguments from capabilities. Example: {"apkPath":"app-debug.apk","allowDowngrade":true}.',
+        additionalProperties: true,
+      },
+    }, ['command']),
+  ];
+}
+
+function fullToolDefinitions() {
+  return [
     bridgeTool('status', 'Read compact bridge status, app info, capture counts, and Flutter layout summary. If default port 18080 times out, agents should retry with the target Android packageName so the CLI can discover the app bridge port.', {
       full: { type: 'boolean', description: 'Return the full raw status payload, including large Flutter widget dumps.' },
     }),
@@ -219,8 +270,10 @@ function toolDefinitions() {
       installerTimeoutMs: { type: 'number', description: 'Maximum time to keep assisting installer screens after adb install exits. Defaults to 90000 ms.' },
       intervalMs: { type: 'number', description: 'Installer polling interval. Defaults to 700 ms.' },
     }, ['apkPath']),
-    bridgeTool('launch_native_test', 'Launch the debug native Android bridge test Activity.'),
-    bridgeTool('launch_flutter', 'Launch the Flutter Activity, optionally with an initial route.'),
+    bridgeTool('launch_app', 'Launch the target package LAUNCHER Activity. If multiple launcher Activities exist, returns launcher_ambiguous with candidates unless activity or component is explicit.', launchProperties()),
+    bridgeTool('launch_activity', 'Launch an explicit Android Activity component, optionally with action/data/category/string extras.', launchProperties()),
+    bridgeTool('launch_native_test', 'Launch the debug native Android bridge test Activity.'),
+    bridgeTool('launch_flutter', 'Launch the Flutter Activity, optionally with an initial route.'),
     bridgeTool('tap', 'Tap device coordinates through ADB.', {
       tapX: { type: 'number' },
       tapY: { type: 'number' },
@@ -233,12 +286,12 @@ function toolDefinitions() {
       targetText: { type: 'string' },
       timeoutSec: { type: 'number' },
     }, ['targetText']),
-    bridgeTool('input_text', 'Set native Android text through the in-app bridge. Use this for Chinese/Unicode; do not use raw adb shell input text for non-ASCII text.', {
+    bridgeTool('input_text', 'Set native Android text through the in-app bridge. Use this for Chinese/Unicode; always pass packageName so the tool targets the intended app.', {
       text: { type: 'string', description: 'Text to set in the focused or coordinate-matched native EditText.' },
       tapX: { type: 'number', description: 'Optional X coordinate used to choose a native EditText target.' },
       tapY: { type: 'number', description: 'Optional Y coordinate used to choose a native EditText target.' },
       hideKeyboard: { type: 'boolean', description: 'Hide the soft keyboard after setting text.' },
-    }, ['text']),
+    }, ['text', 'packageName']),
     bridgeTool('keyboard_state', 'Read Android soft-keyboard visibility from dumpsys input_method.'),
     bridgeTool('hide_keyboard', 'Hide the Android soft keyboard when it is visible.', {
       force: { type: 'boolean', description: 'Send keyboard-dismiss keys even when the visibility probe says the keyboard is hidden.' },
@@ -287,14 +340,29 @@ function toolDefinitions() {
   ];
 }
 
-function bridgeTool(name, description, properties = {}, required = []) {
-  return {
-    name,
-    description,
-    inputSchema: baseSchema(properties, required),
-  };
-}
-
+function bridgeTool(name, description, properties = {}, required = []) {
+  return {
+    name,
+    description,
+    inputSchema: baseSchema(properties, required),
+  };
+}
+
+function launchProperties() {
+  return {
+    activity: { type: 'string', description: 'Activity class, such as .MainActivity or com.example.MainActivity.' },
+    component: { type: 'string', description: 'Explicit Android component, such as com.example/.MainActivity.' },
+    action: { type: 'string', description: 'Intent action for explicit Activity launch.' },
+    category: { type: 'string', description: 'Intent category.' },
+    data: { type: 'string', description: 'Intent data URI.' },
+    extra: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      description: 'String intent extras as an object of key/value pairs.',
+    },
+  };
+}
+
 function baseSchema(extraProperties = {}, extraRequired = []) {
   return {
     type: 'object',
@@ -316,19 +384,82 @@ function baseSchema(extraProperties = {}, extraRequired = []) {
   };
 }
 
-function h5TargetSchema() {
-  return {
-    selector: { type: 'string', description: 'CSS selector for the target DOM element.' },
+function h5TargetSchema() {
+  return {
+    selector: { type: 'string', description: 'CSS selector for the target DOM element.' },
     targetText: { type: 'string', description: 'Text, value, aria-label, placeholder, id, name, or role to match.' },
     exact: { type: 'boolean', description: 'Require exact text match instead of substring match.' },
-  };
-}
-
-async function callTool(name, args) {
-  if (name === 'run_smoke') {
-    return runSmoke(args);
-  }
-  const commandMap = {
+  };
+}
+
+const commandDefinitions = [
+  { command: 'status', domain: 'core', summary: 'Read bridge status, app/device metadata, capture counts, and Flutter summary.', targetApp: true, options: ['packageName', 'port', 'serial', 'full'] },
+  { command: 'tree', domain: 'core', summary: 'Read Android View tree from the in-app bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes', 'maxDepth'] },
+  { command: 'uia-tree', domain: 'core', summary: 'Read UIAutomator XML for the current foreground window.', options: ['serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes'] },
+  { command: 'screenshot', domain: 'core', summary: 'Capture a screenshot, with foreground package verification when packageName is supplied.', options: ['serial', 'packageName', 'outFile', 'artifactDir'] },
+  { command: 'logs', domain: 'core', summary: 'Read in-app log records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'network', domain: 'core', summary: 'Read in-app network records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'urlFilter', 'method', 'statusCode', 'noBodies', 'bodyMaxBytes', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'state', domain: 'core', summary: 'Read in-app state records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'events', domain: 'core', summary: 'Read in-app event records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'logcat', domain: 'diagnostics', summary: 'Read Android logcat with optional app pid, tag, level, and grep filters.', options: ['serial', 'packageName', 'pid', 'appPid', 'tag', 'level', 'grep', 'lines', 'since', 'follow', 'durationSec', 'clear'] },
+  { command: 'install-apk', domain: 'app', summary: 'Install an APK and assist device-side installer confirmation screens.', options: ['serial', 'packageName', 'apkPath', 'allowDowngrade', 'streaming', 'installTimeoutMs', 'installerTimeoutMs', 'intervalMs'] },
+  { command: 'launch-app', domain: 'app', summary: 'Launch the target package LAUNCHER Activity and report launcher candidates.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra'] },
+  { command: 'launch-activity', domain: 'app', summary: 'Launch an explicit Android Activity component with optional string extras.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra'] },
+  { command: 'launch-native-test', domain: 'app', summary: 'Launch the debug native bridge test Activity.', targetApp: true, options: ['serial', 'packageName'] },
+  { command: 'launch-flutter', domain: 'app', summary: 'Launch the Flutter Activity, optionally with an initial route.', targetApp: true, options: ['serial', 'packageName', 'initialRoute'] },
+  { command: 'permission-state', domain: 'app', summary: 'Read Android runtime permission state.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
+  { command: 'permission-grant', domain: 'app', summary: 'Grant an Android runtime permission.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
+  { command: 'permission-revoke', domain: 'app', summary: 'Revoke an Android runtime permission.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
+  { command: 'permission-dialog', domain: 'app', summary: 'Tap a visible Android permission dialog allow button.', options: ['serial', 'targetText', 'buttonText', 'resourceId', 'attempts', 'intervalMs', 'exact'] },
+  { command: 'appops-set', domain: 'app', summary: 'Set an Android app-op mode.', targetApp: true, options: ['serial', 'packageName', 'op', 'mode'] },
+  { command: 'tap', domain: 'action', summary: 'Tap device coordinates through ADB.', options: ['serial', 'tapX', 'tapY'] },
+  { command: 'tap-text', domain: 'action', summary: 'Tap a visible Android View node by text/contentDescription through the bridge tree.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'noAutoHideKeyboard'] },
+  { command: 'tap-uia-text', domain: 'action', summary: 'Tap a UIAutomator node by text without relying on the in-app tree.', options: ['serial', 'targetText', 'exact'] },
+  { command: 'wait-text', domain: 'action', summary: 'Wait until text appears in bridge status/tree or UIAutomator output.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'timeoutSec', 'requireText', 'absentText', 'requireActivity'] },
+  { command: 'input-text', domain: 'action', summary: 'Set native Android text through the in-app bridge; use this for Chinese/Unicode.', targetApp: true, options: ['serial', 'packageName', 'text', 'tapX', 'tapY', 'hideKeyboard'] },
+  { command: 'keyboard-state', domain: 'action', summary: 'Read Android soft keyboard visibility.', options: ['serial'] },
+  { command: 'hide-keyboard', domain: 'action', summary: 'Hide the Android soft keyboard.', options: ['serial', 'force', 'intervalMs'] },
+  { command: 'swipe', domain: 'action', summary: 'Swipe device coordinates through ADB.', options: ['serial', 'startX', 'startY', 'endX', 'endY', 'durationMs'] },
+  { command: 'keyevent', domain: 'action', summary: 'Send an Android keyevent through ADB.', options: ['serial', 'keyCode'] },
+  { command: 'flutter-tree', domain: 'flutter', summary: 'Read the latest Flutter layout snapshot.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'flutter-nodes', domain: 'flutter', summary: 'Read Flutter operable nodes.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'flutter-action', domain: 'flutter', summary: 'Dispatch a raw Flutter action payload.', targetApp: true, options: ['serial', 'packageName', 'payload'] },
+  { command: 'tap-flutter-text', domain: 'flutter', summary: 'Tap a Flutter node by visible text.', targetApp: true, options: ['serial', 'packageName', 'targetText'] },
+  { command: 'input-flutter-text', domain: 'flutter', summary: 'Set Flutter TextField text through the Flutter action bridge.', targetApp: true, options: ['serial', 'packageName', 'text', 'tapX', 'tapY', 'hideKeyboard'] },
+  { command: 'scroll-flutter', domain: 'flutter', summary: 'Scroll Flutter content by delta or until text is visible.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'delta', 'maxSwipes'] },
+  { command: 'h5-dom', domain: 'webview', summary: 'Read native Android WebView DOM.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'h5-eval', domain: 'webview', summary: 'Execute JavaScript in the current native Android WebView.', targetApp: true, options: ['serial', 'packageName', 'script'] },
+  { command: 'h5-click', domain: 'webview', summary: 'Click a native WebView element by selector or text.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'exact'] },
+  { command: 'h5-input', domain: 'webview', summary: 'Set text in a native WebView input.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'value', 'exact'] },
+  { command: 'h5-wait', domain: 'webview', summary: 'Wait for native WebView text or selector.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'timeoutSec', 'intervalMs'] },
+  { command: 'h5-scroll', domain: 'webview', summary: 'Scroll native WebView content or a DOM element into view.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'deltaX', 'deltaY'] },
+  { command: 'flutter-h5-dom', domain: 'webview', summary: 'Read DOM through a Flutter H5 adapter.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'flutter-h5-eval', domain: 'webview', summary: 'Execute JavaScript through a Flutter H5 adapter.', targetApp: true, options: ['serial', 'packageName', 'script'] },
+  { command: 'flutter-h5-click', domain: 'webview', summary: 'Click a Flutter H5 DOM element.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'exact'] },
+  { command: 'flutter-h5-input', domain: 'webview', summary: 'Set text in a Flutter H5 input.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'value', 'exact'] },
+  { command: 'flutter-h5-wait', domain: 'webview', summary: 'Wait for Flutter H5 text or selector.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'timeoutSec', 'intervalMs'] },
+  { command: 'flutter-h5-scroll', domain: 'webview', summary: 'Scroll Flutter H5 content or a DOM element into view.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'deltaX', 'deltaY'] },
+  { command: 'webview-pages', domain: 'webview', summary: 'List attachable Android WebView DevTools/CDP pages.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'keepForward'] },
+  { command: 'webview-network', domain: 'webview', summary: 'Capture WebView Network events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'urlFilter', 'durationMs', 'script', 'includeResponseBody', 'bodyMaxBytes', 'maxEvents'] },
+  { command: 'webview-console', domain: 'webview', summary: 'Capture WebView console/log events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'durationMs', 'script', 'maxEvents'] },
+  { command: 'forward', domain: 'advanced', summary: 'Create the ADB port forward for the bridge.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'remove-forward', domain: 'advanced', summary: 'Remove the ADB port forward for the bridge.', options: ['serial', 'port'] },
+  { command: 'smoke', domain: 'diagnostics', summary: 'Run the native sample smoke test.', options: ['serial', 'packageName', 'outFile', 'artifactDir', 'skipFlutterLaunch'] },
+];
+
+const commandByName = new Map(commandDefinitions.map((definition) => [definition.command, definition]));
+
+async function callTool(name, args) {
+  if (name === 'capabilities') {
+    return toolJson(capabilityPayload(args));
+  }
+  if (name === 'run') {
+    return runGeneric(args);
+  }
+  if (name === 'run_smoke') {
+    return runSmoke(args);
+  }
+  const commandMap = {
     flutter_tree: 'flutter-tree',
     h5_dom: 'h5-dom',
     h5_eval: 'h5-eval',
@@ -346,9 +477,11 @@ async function callTool(name, args) {
     tap_flutter_text: 'tap-flutter-text',
     input_flutter_text: 'input-flutter-text',
     uia_tree: 'uia-tree',
-    install_apk: 'install-apk',
-    launch_native_test: 'launch-native-test',
-    launch_flutter: 'launch-flutter',
+    install_apk: 'install-apk',
+    launch_app: 'launch-app',
+    launch_activity: 'launch-activity',
+    launch_native_test: 'launch-native-test',
+    launch_flutter: 'launch-flutter',
     tap_text: 'tap-text',
     wait_text: 'wait-text',
     input_text: 'input-text',
@@ -363,16 +496,86 @@ async function callTool(name, args) {
     appops_set: 'appops-set',
     tap_uia_text: 'tap-uia-text',
     permission_dialog: 'permission-dialog',
-  };
-  const command = commandMap[name] || name;
-  return runBridge(command, args);
-}
+  };
+  const command = commandMap[name] || name;
+  return runBridgeChecked(command, args);
+}
+
+function capabilityPayload(args = {}) {
+  const includeOptions = Boolean(args.includeOptions);
+  const requestedCommand = args.command ? normalizeCommandName(args.command) : '';
+  if (requestedCommand) {
+    const definition = commandByName.get(requestedCommand);
+    return {
+      ok: Boolean(definition),
+      command: requestedCommand,
+      ...(definition ? shapeCommandDefinition(definition, true) : { error: 'unknown_command' }),
+    };
+  }
+
+  const requestedDomain = args.domain ? String(args.domain) : '';
+  const domains = {};
+  for (const definition of commandDefinitions) {
+    if (requestedDomain && definition.domain !== requestedDomain) continue;
+    if (!domains[definition.domain]) domains[definition.domain] = [];
+    domains[definition.domain].push(shapeCommandDefinition(definition, includeOptions));
+  }
+  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, launch-app, UI, WebView, logcat, network, and permission workflows are supported.',
+    domains,
+  };
+}
+
+function shapeCommandDefinition(definition, includeOptions) {
+  return {
+    command: definition.command,
+    summary: definition.summary,
+    targetApp: Boolean(definition.targetApp),
+    ...(includeOptions ? { options: definition.options || [] } : {}),
+  };
+}
+
+async function runGeneric(args = {}) {
+  const command = normalizeCommandName(args.command);
+  if (!commandByName.has(command)) {
+    return toolText(`unknown command: ${args.command || ''}`, true);
+  }
+  const commandArgs = {
+    ...(args.arguments && typeof args.arguments === 'object' ? args.arguments : {}),
+  };
+  for (const key of ['adb', 'serial', 'port', 'packageName']) {
+    if (args[key] !== undefined && commandArgs[key] === undefined) {
+      commandArgs[key] = args[key];
+    }
+  }
+  return runBridgeChecked(command, commandArgs);
+}
+
+function normalizeCommandName(value) {
+  return String(value || '').trim().replace(/_/g, '-');
+}
+
+function runBridgeChecked(command, args = {}) {
+  const definition = commandByName.get(command);
+  if (definition?.targetApp && !args.packageName && !args.port) {
+    return toolText(`${command}: packageName or explicit port is required in MCP mode so the command cannot fall back to a default package.`, true);
+  }
+  return runBridge(command, args);
+}
 
 async function runBridge(command, args) {
   const cliArgs = [cliScript, command];
   addCommonArgs(cliArgs, args);
-  addArg(cliArgs, 'initial-route', args.initialRoute);
-  addArg(cliArgs, 'out-file', args.outFile);
+  addArg(cliArgs, 'initial-route', args.initialRoute);
+  addArg(cliArgs, 'activity', args.activity);
+  addArg(cliArgs, 'component', args.component);
+  addArg(cliArgs, 'action', args.action);
+  addRepeatedArg(cliArgs, 'category', args.category);
+  addArg(cliArgs, 'data', args.data);
+  addExtraArgs(cliArgs, args.extra);
+  addArg(cliArgs, 'out-file', args.outFile);
   addArg(cliArgs, 'artifact-dir', args.artifactDir || defaultArtifactDirFor(command, args));
   addArg(cliArgs, 'apk-path', args.apkPath);
   addArg(cliArgs, 'tap-x', args.tapX);
@@ -459,13 +662,35 @@ function addCommonArgs(cliArgs, args) {
   addArg(cliArgs, 'package-name', args.packageName);
 }
 
-function addArg(cliArgs, name, value) {
-  if (value === undefined || value === null || value === '' || value === false) {
-    return;
-  }
-  cliArgs.push(`--${name}`, String(value));
-}
-
+function addArg(cliArgs, name, value) {
+  if (value === undefined || value === null || value === '' || value === false) {
+    return;
+  }
+  cliArgs.push(`--${name}`, String(value));
+}
+
+function addRepeatedArg(cliArgs, name, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) addArg(cliArgs, name, item);
+    return;
+  }
+  addArg(cliArgs, name, value);
+}
+
+function addExtraArgs(cliArgs, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) addArg(cliArgs, 'extra', item);
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, extraValue] of Object.entries(value)) {
+      addArg(cliArgs, 'extra', `${key}=${extraValue}`);
+    }
+    return;
+  }
+  addArg(cliArgs, 'extra', value);
+}
+
 function runProcess(cliArgs) {
   return new Promise((resolve) => {
     const child = spawn(nodeBinary, cliArgs, {
@@ -490,12 +715,23 @@ function runProcess(cliArgs) {
         code === 0 ? '' : `exitCode: ${code}`,
         retryWithPackageNameHint(cliArgs, stdout, stderr, code),
       ].filter(Boolean).join('\n\n');
-      resolve(toolText(text || 'ok', code !== 0));
-    });
-  });
-}
-
-function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
+      resolve(toolText(text || emptyProcessText(cliArgs), code !== 0));
+    });
+  });
+}
+
+function emptyProcessText(cliArgs) {
+  const command = cliArgs[1] || '';
+  if (command === 'logcat' && cliArgs.includes('--app-pid')) {
+    return 'logcat: no matching lines for current app pid';
+  }
+  if (command === 'logcat') {
+    return 'logcat: no matching lines';
+  }
+  return 'ok';
+}
+
+function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
   if (code === 0 || cliArgs.includes('--package-name') || cliArgs.includes('--port')) {
     return '';
   }
@@ -506,21 +742,25 @@ function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
   return 'agentHint: Default bridge port 18080 accepted the connection but did not answer. If you know the target app, retry this tool with packageName so the CLI can discover that app bridge port.';
 }
 
-function toolText(text, isError = false) {
-  return {
-    content: [
-      {
-        type: 'text',
+function toolText(text, isError = false) {
+  return {
+    content: [
+      {
+        type: 'text',
         text,
       },
     ],
-    isError,
-  };
-}
-
-function sendResult(id, result) {
-  send({ jsonrpc: '2.0', id, result });
-}
+    isError,
+  };
+}
+
+function toolJson(value, isError = false) {
+  return toolText(JSON.stringify(value, null, 2), isError);
+}
+
+function sendResult(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
 
 function sendError(id, code, message) {
   send({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Desktop CLI and MCP server for AI App Bridge.",
   "repository": {
     "type": "git",