mobile-ai-agents 1.0.35 → 1.0.36

package/README.md

@@ -11,7 +11,7 @@ Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Un
 [![GitHub Stars](https://img.shields.io/github/stars/salmanashraf/mobile-agency?style=social)](https://github.com/salmanashraf/mobile-agency/stargazers)
 [![Platform](https://img.shields.io/badge/platforms-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20Unity%20%7C%20Unreal-brightgreen)](#core-loops-and-platform-plugins)
 
-[Installation Guide](docs/installation.md) · [Core Loops](docs/core-loops.md) · [mobile-karpathy](mobile-karpathy.md) · [Wiki](https://github.com/salmanashraf/mobile-agency/wiki) · [Getting Started](docs/getting-started.md) · [Contributing](CONTRIBUTING.md)
+[Installation Guide](docs/installation.md) · [Android Device Setup](docs/android-device-setup.md) · [Core Loops](docs/core-loops.md) · [mobile-karpathy](mobile-karpathy.md) · [Wiki](https://github.com/salmanashraf/mobile-ai-agents/wiki) · [Getting Started](docs/getting-started.md) · [Contributing](CONTRIBUTING.md)
 
 > AI agents, skills, and Loop Engineering workflows for building, testing, reviewing, and shipping Android, iOS, Flutter, React Native, Unity, and Unreal apps.
 
@@ -398,6 +398,14 @@ Mobile MCP fits the QA stage next: use it for emulator, simulator, or real-devic
 
 Mobile MCP gives Mobile AI Agents a device automation layer for iOS and Android simulators, emulators, and real devices.
 
+Prepare an Android project with environment diagnostics and settings-preserving MCP setup:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+npx mobile-ai-agents mcp setup --client claude
+npx mobile-ai-agents mcp config init --app-id com.example.app
+```
+
 ```
 /mobile-mcp-qa
 1. List devices
@@ -408,7 +416,7 @@ Mobile MCP gives Mobile AI Agents a device automation layer for iOS and Android
 6. Produce MOBILE_MCP_QA_REPORT.md
 ```
 
-Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Full guide: [docs/mobile-mcp.md](docs/mobile-mcp.md)
+Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Guides: [Android Device QA Setup](docs/android-device-setup.md), [wiki guide](https://github.com/salmanashraf/mobile-ai-agents/wiki/Android-Device-QA-Setup), and [Mobile MCP Integration](docs/mobile-mcp.md).
 
 ### Device Proof Reports
 

package/cli/commands/doctor.js

@@ -0,0 +1,182 @@
+'use strict';
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { parseOptions } = require('../lib/options');
+const { inspectMcpConfiguration, loadProjectConfig } = require('./mcp');
+
+function executableOnPath(name, env, fsImpl) {
+  const entries = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const entry of entries) {
+    const candidate = path.join(entry, name);
+    if (fsImpl.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function defaultRunner(command, args, env) {
+  const result = childProcess.spawnSync(command, args, {
+    encoding: 'utf8',
+    env,
+    timeout: 10000,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error ? result.error.message : '',
+  };
+}
+
+function resultStatus(checks) {
+  if (checks.some(check => check.status === 'FAIL')) return 'FAIL';
+  if (checks.some(check => check.status === 'WARN')) return 'WARN';
+  return 'PASS';
+}
+
+function parseAdbDevices(output) {
+  return String(output)
+    .split(/\r?\n/)
+    .slice(1)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => {
+      const [serial, state] = line.split(/\s+/);
+      return { serial, state };
+    });
+}
+
+function collectAndroidDoctor(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const env = options.env || process.env;
+  const homedir = options.homedir || os.homedir();
+  const fsImpl = options.fsImpl || fs;
+  const runner = options.runner || defaultRunner;
+  const checks = [];
+  const sdkCandidates = [
+    env.ANDROID_HOME,
+    env.ANDROID_SDK_ROOT,
+    path.join(homedir, 'Library', 'Android', 'sdk'),
+    path.join(homedir, 'Android', 'Sdk'),
+  ].filter(Boolean);
+  const sdkRoot = sdkCandidates.find(candidate => fsImpl.existsSync(candidate));
+
+  checks.push(sdkRoot
+    ? { id: 'android-sdk', status: 'PASS', summary: `Android SDK found at ${sdkRoot}` }
+    : {
+      id: 'android-sdk',
+      status: 'FAIL',
+      summary: 'Android SDK was not found.',
+      action: 'Install Android Studio/SDK and set ANDROID_HOME or ANDROID_SDK_ROOT.',
+    });
+
+  const adb = executableOnPath('adb', env, fsImpl) ||
+    (sdkRoot && fsImpl.existsSync(path.join(sdkRoot, 'platform-tools', 'adb')) ? path.join(sdkRoot, 'platform-tools', 'adb') : null);
+  if (!adb) {
+    checks.push({
+      id: 'adb',
+      status: 'FAIL',
+      summary: 'adb was not found.',
+      action: 'Install Android SDK Platform-Tools and add platform-tools to PATH.',
+    });
+  } else {
+    const version = runner(adb, ['version'], env);
+    checks.push(version.status === 0
+      ? { id: 'adb', status: 'PASS', summary: `adb available at ${adb}`, details: version.stdout.split(/\r?\n/)[0] }
+      : { id: 'adb', status: 'FAIL', summary: 'adb exists but could not run.', details: version.stderr || version.error, action: 'Repair Platform-Tools or PATH permissions.' });
+
+    const devicesResult = runner(adb, ['devices'], env);
+    const devices = devicesResult.status === 0 ? parseAdbDevices(devicesResult.stdout) : [];
+    checks.push(devicesResult.status !== 0
+      ? { id: 'android-devices', status: 'FAIL', summary: 'adb could not list devices.', details: devicesResult.stderr || devicesResult.error, action: 'Restart adb and reconnect or authorize the target device.' }
+      : devices.some(device => device.state === 'device')
+        ? { id: 'android-devices', status: 'PASS', summary: `${devices.filter(device => device.state === 'device').length} ready Android device(s).`, details: devices }
+        : { id: 'android-devices', status: 'WARN', summary: 'No ready Android device or emulator is connected.', details: devices, action: 'Start an emulator or connect and authorize a device.' });
+  }
+
+  const emulator = executableOnPath('emulator', env, fsImpl) ||
+    (sdkRoot && fsImpl.existsSync(path.join(sdkRoot, 'emulator', 'emulator')) ? path.join(sdkRoot, 'emulator', 'emulator') : null);
+  if (!emulator) {
+    checks.push({
+      id: 'android-emulator',
+      status: 'WARN',
+      summary: 'Android Emulator command was not found.',
+      action: 'Install Android Emulator from SDK Manager if emulator QA is required.',
+    });
+  } else {
+    const avdResult = runner(emulator, ['-list-avds'], env);
+    const avds = avdResult.status === 0 ? avdResult.stdout.split(/\r?\n/).map(v => v.trim()).filter(Boolean) : [];
+    checks.push(avdResult.status !== 0
+      ? { id: 'android-emulator', status: 'WARN', summary: 'Emulator exists but AVDs could not be listed.', details: avdResult.stderr || avdResult.error, action: 'Open Android Studio Device Manager and repair the emulator installation.' }
+      : avds.length
+        ? { id: 'android-emulator', status: 'PASS', summary: `${avds.length} Android Virtual Device image(s) available.`, details: avds }
+        : { id: 'android-emulator', status: 'WARN', summary: 'No Android Virtual Device images are configured.', action: 'Create an AVD in Android Studio Device Manager.' });
+  }
+
+  const mcpConfigs = inspectMcpConfiguration({ cwd, homedir, fsImpl });
+  checks.push(mcpConfigs.length
+    ? { id: 'mobile-mcp', status: 'PASS', summary: `Mobile MCP configured for ${mcpConfigs.map(item => item.client).join(', ')}.`, details: mcpConfigs.map(item => item.file) }
+    : { id: 'mobile-mcp', status: 'WARN', summary: 'Mobile MCP is not configured for a supported client.', action: 'Run mobile-ai-agents mcp setup --client <client>.' });
+
+  const project = loadProjectConfig({ cwd, fsImpl, configPath: options.configPath });
+  if (!project.config) {
+    checks.push({
+      id: 'project-config',
+      status: 'WARN',
+      summary: 'Android device QA project configuration is missing.',
+      action: 'Run mobile-ai-agents mcp config init --app-id com.example.app.',
+    });
+  } else if (project.errors.length) {
+    checks.push({
+      id: 'project-config',
+      status: 'FAIL',
+      summary: 'Android device QA project configuration is invalid.',
+      details: project.errors,
+      action: 'Run mobile-ai-agents mcp config validate and correct the listed fields.',
+    });
+  } else {
+    const apk = path.resolve(cwd, project.config.apkPath);
+    checks.push(fsImpl.existsSync(apk)
+      ? { id: 'project-config', status: 'PASS', summary: 'Android device QA project configuration is valid.', details: project.file }
+      : { id: 'project-config', status: 'WARN', summary: 'Project configuration is valid, but the APK does not exist yet.', details: project.config.apkPath, action: 'Build the configured APK before device QA.' });
+  }
+
+  return {
+    platform: 'android',
+    status: resultStatus(checks),
+    checkedAt: new Date().toISOString(),
+    checks,
+  };
+}
+
+function printDoctorReport(report) {
+  console.log('');
+  console.log('  Android Environment Doctor');
+  console.log(`  Result: ${report.status}`);
+  console.log('');
+  for (const check of report.checks) {
+    const icon = check.status === 'PASS' ? '✓' : check.status === 'WARN' ? '!' : '✗';
+    console.log(`  ${icon} [${check.status}] ${check.summary}`);
+    if (check.action) console.log(`    Action: ${check.action}`);
+  }
+  console.log('');
+}
+
+async function cmdDoctor(args) {
+  const opts = parseOptions(args);
+  const platform = opts.platform === true ? '' : opts.platform;
+  if (platform !== 'android') throw new Error('doctor currently requires --platform android.');
+  const report = collectAndroidDoctor({ configPath: opts.config === true ? undefined : opts.config });
+  if (opts.json) console.log(JSON.stringify(report, null, 2));
+  else printDoctorReport(report);
+  if (report.status === 'FAIL') process.exitCode = 1;
+  return report;
+}
+
+module.exports = {
+  cmdDoctor,
+  collectAndroidDoctor,
+  parseAdbDevices,
+};

package/cli/commands/mcp.js

@@ -0,0 +1,330 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { parseOptions } = require('../lib/options');
+
+const SERVER_NAME = 'mobile-mcp';
+const SERVER_COMMAND = 'npx';
+const SERVER_ARGS = ['-y', '@mobilenext/mobile-mcp@latest'];
+const PROJECT_CONFIG_PATH = path.join('.mobile-ai-agents', 'android-device.json');
+
+const JSON_CLIENTS = {
+  claude: ({ cwd }) => path.join(cwd, '.mcp.json'),
+  cursor: ({ cwd }) => path.join(cwd, '.cursor', 'mcp.json'),
+  windsurf: ({ homedir }) => path.join(homedir, '.codeium', 'windsurf', 'mcp_config.json'),
+};
+
+function ensureParent(file, fsImpl = fs) {
+  fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+function readJsonObject(file, fsImpl = fs) {
+  if (!fsImpl.existsSync(file)) return {};
+  try {
+    const value = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+      throw new Error('top-level value must be an object');
+    }
+    return value;
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${file}: ${error.message}`);
+  }
+}
+
+function resolveClientConfig(client, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const homedir = options.homedir || os.homedir();
+  if (options.configPath) return path.resolve(cwd, options.configPath);
+  if (client === 'codex') return path.join(homedir, '.codex', 'config.toml');
+  const resolver = JSON_CLIENTS[client];
+  if (!resolver) {
+    throw new Error('Unsupported MCP client. Use claude, cursor, windsurf, or codex.');
+  }
+  return resolver({ cwd, homedir });
+}
+
+function setupJsonClient(file, fsImpl = fs) {
+  const config = readJsonObject(file, fsImpl);
+  const servers = config.mcpServers && typeof config.mcpServers === 'object' && !Array.isArray(config.mcpServers)
+    ? { ...config.mcpServers }
+    : {};
+  const desired = { command: SERVER_COMMAND, args: SERVER_ARGS };
+  const current = servers[SERVER_NAME];
+  const unchanged = current &&
+    current.command === desired.command &&
+    JSON.stringify(current.args) === JSON.stringify(desired.args);
+
+  if (unchanged) return { changed: false, file, clientFormat: 'json' };
+
+  config.mcpServers = { ...servers, [SERVER_NAME]: desired };
+  ensureParent(file, fsImpl);
+  fsImpl.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+  return { changed: true, file, clientFormat: 'json' };
+}
+
+function setupCodexClient(file, fsImpl = fs) {
+  const existing = fsImpl.existsSync(file) ? fsImpl.readFileSync(file, 'utf8') : '';
+  const block = [
+    '[mcp_servers.mobile-mcp]',
+    `command = "${SERVER_COMMAND}"`,
+    `args = ["${SERVER_ARGS.join('", "')}"]`,
+  ].join('\n');
+  const sectionPattern = /^\[mcp_servers\.(?:mobile-mcp|"mobile-mcp")\]\s*$/m;
+  const match = sectionPattern.exec(existing);
+  let next;
+
+  if (!match) {
+    const prefix = existing.trimEnd();
+    next = `${prefix}${prefix ? '\n\n' : ''}${block}\n`;
+  } else {
+    const sectionStart = match.index;
+    const afterHeader = sectionStart + match[0].length;
+    const remainder = existing.slice(afterHeader);
+    const nextSection = /^\s*\[[^\]]+\]/m.exec(remainder);
+    const sectionEnd = nextSection ? afterHeader + nextSection.index : existing.length;
+    next = `${existing.slice(0, sectionStart)}${block}\n${existing.slice(sectionEnd).replace(/^\s+/, '')}`;
+  }
+
+  if (next === existing) return { changed: false, file, clientFormat: 'toml' };
+  ensureParent(file, fsImpl);
+  fsImpl.writeFileSync(file, next);
+  return { changed: true, file, clientFormat: 'toml' };
+}
+
+function setupMcpClient(client, options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  const file = resolveClientConfig(client, options);
+  const result = client === 'codex'
+    ? setupCodexClient(file, fsImpl)
+    : setupJsonClient(file, fsImpl);
+  return { ...result, client, server: SERVER_NAME };
+}
+
+function defaultProjectConfig(values = {}) {
+  return {
+    version: 1,
+    platform: 'android',
+    appId: values.appId || '',
+    apkPath: values.apkPath || 'app/build/outputs/apk/debug/app-debug.apk',
+    device: values.device || 'auto',
+    flow: values.flow || ['Launch app', 'Verify the initial screen'],
+    timeouts: {
+      bootMs: values.bootMs || 120000,
+      actionMs: values.actionMs || 15000,
+    },
+    evidenceDir: values.evidenceDir || '.mobile-ai-agents/evidence',
+  };
+}
+
+function validateProjectConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return ['Configuration must be a JSON object.'];
+  }
+  if (config.version !== 1) errors.push('version must be 1.');
+  if (config.platform !== 'android') errors.push('platform must be "android".');
+  if (typeof config.appId !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/.test(config.appId)) {
+    errors.push('appId must be a valid Android application ID such as com.example.app.');
+  }
+  if (typeof config.apkPath !== 'string' || !config.apkPath.endsWith('.apk')) {
+    errors.push('apkPath must point to an .apk file.');
+  }
+  if (typeof config.device !== 'string' || !config.device.trim()) {
+    errors.push('device must be "auto", an emulator name, or a device serial.');
+  }
+  if (!Array.isArray(config.flow) || !config.flow.length || config.flow.some(step => typeof step !== 'string' || !step.trim())) {
+    errors.push('flow must be a non-empty array of test steps.');
+  }
+  if (!config.timeouts || !Number.isInteger(config.timeouts.bootMs) || config.timeouts.bootMs <= 0) {
+    errors.push('timeouts.bootMs must be a positive integer.');
+  }
+  if (!config.timeouts || !Number.isInteger(config.timeouts.actionMs) || config.timeouts.actionMs <= 0) {
+    errors.push('timeouts.actionMs must be a positive integer.');
+  }
+  if (typeof config.evidenceDir !== 'string' || !config.evidenceDir.trim()) {
+    errors.push('evidenceDir must be a non-empty path.');
+  }
+  return errors;
+}
+
+function projectConfigFile(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  return path.resolve(cwd, options.configPath || PROJECT_CONFIG_PATH);
+}
+
+function initProjectConfig(values = {}, options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  const file = projectConfigFile(options);
+  const existing = readJsonObject(file, fsImpl);
+  const base = Object.keys(existing).length ? existing : defaultProjectConfig();
+  const next = {
+    ...base,
+    version: 1,
+    platform: 'android',
+    appId: values.appId !== undefined ? values.appId : base.appId,
+    apkPath: values.apkPath !== undefined ? values.apkPath : base.apkPath,
+    device: values.device !== undefined ? values.device : base.device,
+    flow: values.flow !== undefined ? values.flow : base.flow,
+    timeouts: {
+      ...(base.timeouts || {}),
+      bootMs: values.bootMs !== undefined ? values.bootMs : base.timeouts?.bootMs || 120000,
+      actionMs: values.actionMs !== undefined ? values.actionMs : base.timeouts?.actionMs || 15000,
+    },
+    evidenceDir: values.evidenceDir !== undefined ? values.evidenceDir : base.evidenceDir,
+  };
+  const errors = validateProjectConfig(next);
+  if (errors.length) throw new Error(`Invalid Android device configuration:\n- ${errors.join('\n- ')}`);
+
+  const serialized = `${JSON.stringify(next, null, 2)}\n`;
+  const current = fsImpl.existsSync(file) ? fsImpl.readFileSync(file, 'utf8') : '';
+  if (current !== serialized) {
+    ensureParent(file, fsImpl);
+    fsImpl.writeFileSync(file, serialized);
+  }
+  return { changed: current !== serialized, file, config: next };
+}
+
+function loadProjectConfig(options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  const file = projectConfigFile(options);
+  if (!fsImpl.existsSync(file)) return { file, config: null, errors: ['Project configuration does not exist.'] };
+  const config = readJsonObject(file, fsImpl);
+  return { file, config, errors: validateProjectConfig(config) };
+}
+
+function knownMcpConfigFiles(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const homedir = options.homedir || os.homedir();
+  return [
+    { client: 'claude', format: 'json', file: path.join(cwd, '.mcp.json') },
+    { client: 'cursor', format: 'json', file: path.join(cwd, '.cursor', 'mcp.json') },
+    { client: 'windsurf', format: 'json', file: path.join(homedir, '.codeium', 'windsurf', 'mcp_config.json') },
+    { client: 'codex', format: 'toml', file: path.join(homedir, '.codex', 'config.toml') },
+  ];
+}
+
+function inspectMcpConfiguration(options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  const found = [];
+  for (const candidate of knownMcpConfigFiles(options)) {
+    if (!fsImpl.existsSync(candidate.file)) continue;
+    try {
+      let configured;
+      if (candidate.format === 'json') {
+        const server = readJsonObject(candidate.file, fsImpl).mcpServers?.[SERVER_NAME];
+        configured = server?.command === SERVER_COMMAND && JSON.stringify(server.args) === JSON.stringify(SERVER_ARGS);
+      } else {
+        const content = fsImpl.readFileSync(candidate.file, 'utf8');
+        const header = /^\[mcp_servers\.(?:mobile-mcp|"mobile-mcp")\]\s*$/m.exec(content);
+        if (!header) {
+          configured = false;
+        } else {
+          const remainder = content.slice(header.index + header[0].length);
+          const nextSection = /^\s*\[[^\]]+\]/m.exec(remainder);
+          const section = nextSection ? remainder.slice(0, nextSection.index) : remainder;
+          configured = /^\s*command\s*=\s*"npx"\s*$/m.test(section) &&
+            /^\s*args\s*=\s*\[\s*"-y"\s*,\s*"@mobilenext\/mobile-mcp@latest"\s*\]\s*$/m.test(section);
+        }
+      }
+      if (configured) found.push(candidate);
+    } catch {
+      // Invalid files are reported by setup/validation rather than hidden as configured.
+    }
+  }
+  return found;
+}
+
+function printMcpHelp() {
+  console.log('');
+  console.log('  Mobile MCP setup');
+  console.log('');
+  console.log('  Commands:');
+  console.log('    mobile-ai-agents mcp setup --client <claude|cursor|windsurf|codex>');
+  console.log('    mobile-ai-agents mcp config init --app-id com.example.app [options]');
+  console.log('    mobile-ai-agents mcp config validate [--json]');
+  console.log('');
+  console.log('  Config options:');
+  console.log('    --apk <path>                    APK path');
+  console.log('    --device <auto|name|serial>     Device selection');
+  console.log('    --flow "step 1|step 2"          Ordered test flow');
+  console.log('    --boot-timeout-ms <number>      Emulator boot timeout');
+  console.log('    --action-timeout-ms <number>    Per-action timeout');
+  console.log('    --evidence-dir <path>           Screenshots and reports');
+  console.log('    --config <path>                 Override target config path');
+  console.log('');
+}
+
+async function cmdMcp(args) {
+  const opts = parseOptions(args);
+  const [sub, action] = opts._;
+
+  if (!sub || sub === 'help') {
+    printMcpHelp();
+    return;
+  }
+
+  if (sub === 'setup') {
+    if (!opts.client || opts.client === true) throw new Error('mcp setup requires --client.');
+    const result = setupMcpClient(String(opts.client), { configPath: opts.config === true ? undefined : opts.config });
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log('');
+      console.log(`  ${result.changed ? '✓ Configured' : '✓ Already configured'} mobile-mcp for ${result.client}`);
+      console.log(`  File: ${result.file}`);
+      console.log('');
+    }
+    return result;
+  }
+
+  if (sub === 'config' && action === 'init') {
+    const flow = typeof opts.flow === 'string' ? opts.flow.split('|').map(v => v.trim()).filter(Boolean) : undefined;
+    const result = initProjectConfig({
+      appId: opts['app-id'] === true ? undefined : opts['app-id'],
+      apkPath: opts.apk === true ? undefined : opts.apk,
+      device: opts.device === true ? undefined : opts.device,
+      flow,
+      bootMs: opts['boot-timeout-ms'] ? Number(opts['boot-timeout-ms']) : undefined,
+      actionMs: opts['action-timeout-ms'] ? Number(opts['action-timeout-ms']) : undefined,
+      evidenceDir: opts['evidence-dir'] === true ? undefined : opts['evidence-dir'],
+    }, { configPath: opts.config === true ? undefined : opts.config });
+    console.log('');
+    console.log(`  ${result.changed ? '✓ Wrote' : '✓ Unchanged'} ${result.file}`);
+    console.log('');
+    return result;
+  }
+
+  if (sub === 'config' && action === 'validate') {
+    const result = loadProjectConfig({ configPath: opts.config === true ? undefined : opts.config });
+    if (opts.json) {
+      console.log(JSON.stringify({ valid: result.errors.length === 0, ...result }, null, 2));
+    } else if (result.errors.length) {
+      console.log('');
+      console.log(`  ✗ Invalid ${result.file}`);
+      result.errors.forEach(error => console.log(`    - ${error}`));
+      console.log('');
+    } else {
+      console.log('');
+      console.log(`  ✓ Valid ${result.file}`);
+      console.log('');
+    }
+    if (result.errors.length) process.exitCode = 1;
+    return result;
+  }
+
+  throw new Error('Unknown mcp command. Use mcp help.');
+}
+
+module.exports = {
+  PROJECT_CONFIG_PATH,
+  cmdMcp,
+  defaultProjectConfig,
+  initProjectConfig,
+  inspectMcpConfiguration,
+  loadProjectConfig,
+  resolveClientConfig,
+  setupMcpClient,
+  validateProjectConfig,
+};

package/cli/commands/router.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { cmdDoctor } = require('./doctor');
+const { cmdMcp } = require('./mcp');
+
+function createCommandRouter(legacyHandlers) {
+  const routes = new Map([
+    ['start', legacyHandlers.start],
+    ['install', legacyHandlers.install],
+    ['add', legacyHandlers.add],
+    ['memory', legacyHandlers.memory],
+    ['list', legacyHandlers.list],
+    ['doctor', cmdDoctor],
+    ['mcp', cmdMcp],
+    ['help', legacyHandlers.help],
+    ['--help', legacyHandlers.help],
+    ['-h', legacyHandlers.help],
+  ]);
+
+  return async function routeCommand(command, args = []) {
+    if (command === undefined) return legacyHandlers.help(args);
+    const handler = routes.get(command);
+    if (!handler) {
+      const error = new Error(`Unknown command: ${command}`);
+      error.code = 'UNKNOWN_COMMAND';
+      throw error;
+    }
+    return handler(args);
+  };
+}
+
+module.exports = { createCommandRouter };

package/cli/index.js

@@ -6,6 +6,8 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
+const { createCommandRouter } = require('./commands/router');
+const { parseOptions } = require('./lib/options');
 
 const REPO = 'salmanashraf/mobile-agency';
 const BRANCH = 'main';
@@ -283,26 +285,6 @@ function slugify(s) {
     .slice(0, 80) || 'memory';
 }
 
-function parseOptions(args) {
-  const out = { _: [] };
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (!arg.startsWith('--')) {
-      out._.push(arg);
-      continue;
-    }
-    const key = arg.slice(2);
-    const next = args[i + 1];
-    if (!next || next.startsWith('--')) {
-      out[key] = true;
-    } else {
-      out[key] = next;
-      i++;
-    }
-  }
-  return out;
-}
-
 function readStdinIfPiped() {
   if (process.stdin.isTTY) return '';
   try {
@@ -1401,6 +1383,8 @@ function cmdList() {
   console.log(dim('    npx mobile-ai-agents add skill grill-mobile          # one skill'));
   console.log(dim('    npx mobile-ai-agents add workflow feature-ship       # one workflow'));
   console.log(dim('    npx mobile-ai-agents memory init                     # local Mobile Memory'));
+  console.log(dim('    npx mobile-ai-agents doctor --platform android       # check Android setup'));
+  console.log(dim('    npx mobile-ai-agents mcp setup --client claude       # configure Mobile MCP'));
   console.log('');
 }
 
@@ -1413,6 +1397,8 @@ function cmdHelp() {
   console.log(`    ${bold('install')}                         Install agents, skills, and workflows`);
   console.log(`    ${bold('add')} agent|skill|workflow <name>  Install a single item`);
   console.log(`    ${bold('memory')} init|capture|search|...    Local Mobile Memory store`);
+  console.log(`    ${bold('doctor')} --platform android          Check SDK, adb, emulator, MCP, and project config`);
+  console.log(`    ${bold('mcp')} setup|config                  Configure Mobile MCP and Android device QA`);
   console.log(`    ${bold('list')}                            List all available agents, skills, and workflows`);
   console.log(`    ${bold('help')}                            Show this help`);
   console.log('');
@@ -1447,6 +1433,11 @@ function cmdHelp() {
   console.log(dim('    npx mobile-ai-agents add workflow feature-ship'));
   console.log(dim('    npx mobile-ai-agents memory init'));
   console.log(dim('    npx mobile-ai-agents memory capture --type decision --text "Use Room for offline persistence"'));
+  console.log(dim('    npx mobile-ai-agents doctor --platform android'));
+  console.log(dim('    npx mobile-ai-agents doctor --platform android --json'));
+  console.log(dim('    npx mobile-ai-agents mcp setup --client codex'));
+  console.log(dim('    npx mobile-ai-agents mcp config init --app-id com.example.app'));
+  console.log(dim('    npx mobile-ai-agents mcp config validate'));
   console.log('');
   console.log(dim(`  github.com/${REPO}`));
   console.log('');
@@ -1454,28 +1445,24 @@ function cmdHelp() {
 
 // ─── Main ────────────────────────────────────────────────────────────────────
 
+const routeCommand = createCommandRouter({
+  start: cmdStart,
+  install: cmdInstall,
+  add: cmdAdd,
+  memory: cmdMemory,
+  list: cmdList,
+  help: cmdHelp,
+});
+
 async function main() {
   const [,, cmd, ...args] = process.argv;
 
   try {
-    switch (cmd) {
-      case 'start':   await cmdStart(args);   break;
-      case 'install': await cmdInstall(args); break;
-      case 'add':     await cmdAdd(args);     break;
-      case 'memory':  cmdMemory(args);        break;
-      case 'list':    cmdList();              break;
-      case 'help':
-      case '--help':
-      case '-h':
-      case undefined: cmdHelp();              break;
-      default:
-        console.error(`\n  Unknown command: ${cmd}\n`);
-        cmdHelp();
-        process.exit(1);
-    }
+    await routeCommand(cmd, args);
   } catch (e) {
-    console.error(`\n  Error: ${e.message}\n`);
-    process.exit(1);
+    console.error(`\n  ${e.code === 'UNKNOWN_COMMAND' ? e.message : `Error: ${e.message}`}\n`);
+    if (e.code === 'UNKNOWN_COMMAND') cmdHelp();
+    process.exitCode = 1;
   }
 }
 

package/cli/lib/options.js

@@ -0,0 +1,24 @@
+'use strict';
+
+function parseOptions(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      out._.push(arg);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (!next || next.startsWith('--')) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i++;
+    }
+  }
+  return out;
+}
+
+module.exports = { parseOptions };

package/docs/android-device-setup.md

@@ -0,0 +1,138 @@
+# Android Device QA Setup
+
+Prepare an Android project for the `/mobile-mcp-qa` skill with repeatable environment checks, MCP configuration, and a project-level test definition.
+
+This setup layer verifies prerequisites and records the intended QA flow. Device-flow execution is tracked separately in [issue #54](https://github.com/salmanashraf/mobile-ai-agents/issues/54).
+
+## Prerequisites
+
+- Node.js 18 or newer
+- Android Studio with Android SDK Platform-Tools
+- Android Emulator plus at least one AVD, or an authorized physical device
+- Claude Code, Cursor, Windsurf, or Codex
+
+## 1. Check the Android Environment
+
+Run from the mobile app project:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+```
+
+The doctor checks:
+
+- `ANDROID_HOME`, `ANDROID_SDK_ROOT`, and common SDK locations
+- `adb` availability and version
+- connected and authorized devices
+- Android Emulator installation and configured AVDs
+- Mobile MCP configuration for supported AI clients
+- `.mobile-ai-agents/android-device.json` validity and APK availability
+
+Use machine-readable output in CI or scripts:
+
+```bash
+npx mobile-ai-agents doctor --platform android --json
+```
+
+Exit code `1` means at least one required check failed. Warnings identify optional or not-yet-ready items, such as a missing APK before the first build.
+
+## 2. Configure Mobile MCP
+
+Choose the client you use:
+
+```bash
+npx mobile-ai-agents mcp setup --client claude
+npx mobile-ai-agents mcp setup --client cursor
+npx mobile-ai-agents mcp setup --client windsurf
+npx mobile-ai-agents mcp setup --client codex
+```
+
+The command adds this server without deleting existing settings or MCP servers:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+}
+```
+
+Running the same setup command again is safe and leaves an already-correct file unchanged.
+
+Default configuration files:
+
+| Client | File |
+|---|---|
+| Claude Code | `<project>/.mcp.json` |
+| Cursor | `<project>/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Codex | `~/.codex/config.toml` |
+
+Use `--config <path>` to target a different client config file.
+
+## 3. Define the Project QA Flow
+
+Create `.mobile-ai-agents/android-device.json`:
+
+```bash
+npx mobile-ai-agents mcp config init \
+  --app-id com.example.app \
+  --apk app/build/outputs/apk/debug/app-debug.apk \
+  --device auto \
+  --flow "Launch app|Open settings|Enable notifications|Restart app"
+```
+
+Generated shape:
+
+```json
+{
+  "version": 1,
+  "platform": "android",
+  "appId": "com.example.app",
+  "apkPath": "app/build/outputs/apk/debug/app-debug.apk",
+  "device": "auto",
+  "flow": [
+    "Launch app",
+    "Open settings",
+    "Enable notifications",
+    "Restart app"
+  ],
+  "timeouts": {
+    "bootMs": 120000,
+    "actionMs": 15000
+  },
+  "evidenceDir": ".mobile-ai-agents/evidence"
+}
+```
+
+You can also copy [the configuration template](../templates/android-device-config.json).
+
+Validate after editing:
+
+```bash
+npx mobile-ai-agents mcp config validate
+npx mobile-ai-agents mcp config validate --json
+```
+
+## 4. Run the Skill
+
+After the doctor has no failures, restart the AI client so it loads Mobile MCP, then invoke:
+
+```text
+/mobile-mcp-qa
+```
+
+The skill uses the app ID, build, target device, expected flow, and evidence requirements to guide device QA. See [Mobile MCP Integration](mobile-mcp.md) for the full prompt format and report output.
+
+## Troubleshooting
+
+| Result | Fix |
+|---|---|
+| Android SDK not found | Install the SDK and set `ANDROID_HOME` or `ANDROID_SDK_ROOT`. |
+| `adb` not found | Install Platform-Tools and add `<sdk>/platform-tools` to `PATH`. |
+| No ready device | Start an AVD or connect a device, enable USB debugging, and authorize the computer. |
+| No AVD configured | Create one in Android Studio Device Manager. |
+| MCP not configured | Run `mcp setup --client <client>`, then restart the client. |
+| Invalid project config | Run `mcp config validate` and correct every listed field. |
+| APK missing | Build the configured APK before device QA. |
+
+Do not use production accounts or irreversible actions during automated QA. Prefer test builds, sandbox credentials, and disposable data.

package/docs/index.html

@@ -679,7 +679,12 @@
       <span class="comment"># Or just one Android agent</span><br>
       <span class="cmd2">npx mobile-ai-agents add agent axiom</span><br>
       <span class="cmd2">npx mobile-ai-agents add agent anr-investigation</span><br>
-      <span class="cmd2">npx mobile-ai-agents add agent memory-leak-analyzer</span>
+      <span class="cmd2">npx mobile-ai-agents add agent memory-leak-analyzer</span><br><br>
+      <span class="comment"># Prepare Android device QA with Mobile MCP</span><br>
+      <span class="cmd2">npx mobile-ai-agents doctor</span> <span class="flag">--platform</span> <span class="val">android</span><br>
+      <span class="cmd2">npx mobile-ai-agents mcp setup</span> <span class="flag">--client</span> <span class="val">claude</span><br>
+      <span class="cmd2">npx mobile-ai-agents mcp config init</span> <span class="flag">--app-id</span> <span class="val">com.example.app</span><br><br>
+      <a href="android-device-setup.md">Read the Android Device QA Setup guide →</a>
     </div>
     <div class="code-block" id="tab-cursor" style="display:none">
       <span class="comment"># Install for Cursor (.cursorrules in current project)</span><br>

package/docs/installation.md

@@ -60,6 +60,14 @@ node --version
 
 If this prints a version like `v18.x`, `v20.x`, or newer, you are ready.
 
+If you plan to use `/mobile-mcp-qa` with Android, also install Android Studio, Platform-Tools, and an emulator image or connect an authorized device. Verify the setup with:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+```
+
+Then follow the [Android Device QA Setup guide](android-device-setup.md) to configure Mobile MCP and the project test flow.
+
 ---
 
 ## Step 1: Pick Your AI Tool

package/docs/mobile-mcp.md

@@ -33,6 +33,20 @@ It exposes tools for:
 
 ## Install
 
+### Automated setup
+
+From an Android app project, run the environment doctor and configure your AI client:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+npx mobile-ai-agents mcp setup --client <claude|cursor|windsurf|codex>
+npx mobile-ai-agents mcp config init --app-id com.example.app
+```
+
+The setup command preserves existing settings and is idempotent. The project config records the app ID, APK, target device, flow, timeouts, and evidence directory. See [Android Device QA Setup](android-device-setup.md) for the full command reference and troubleshooting.
+
+### Manual setup
+
 Standard MCP config:
 
 ```json

package/docs/release-process.md

@@ -51,6 +51,7 @@ test -f "$tmp_home/.claude/commands/<name>.md"
 
 ```bash
 git diff --check
+npm test
 node --check cli/index.js
 bash -n install.sh
 node cli/index.js list

package/docs/wiki.md

@@ -41,12 +41,22 @@
 
 For first-time setup, use the dedicated [Installation Guide](installation.md). It explains which command to run for Claude Code, Cursor, Windsurf, GitHub Copilot, and Codex.
 
+For Android device or emulator QA, use the [Android Device QA Setup](android-device-setup.md). It covers the environment doctor, Mobile MCP client setup, and `.mobile-ai-agents/android-device.json` project configuration used by `/mobile-mcp-qa`.
+
 Fast path:
 
 ```bash
 npx mobile-ai-agents install
 ```
 
+Android QA setup:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+npx mobile-ai-agents mcp setup --client claude
+npx mobile-ai-agents mcp config init --app-id com.example.app
+```
+
 Common installs:
 
 | I use... | Run this |

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "mobile-ai-agents",
-  "version": "1.0.35",
+  "version": "1.0.36",
   "description": "AI agents, skills, and Loop Engineering workflows for building, testing, auditing, and releasing mobile apps.",
   "bin": {
     "mobile-ai-agents": "cli/index.js",
     "mobile-agency": "cli/index.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "AGENTS.md",
     "CLAUDE.md",

package/skills/cross-platform/mobile-mcp-qa.md

@@ -16,6 +16,20 @@ Mobile MCP is best used after implementation, during APPFORGE Stage 7 Full QA, a
 
 ## Prerequisites
 
+For Android, use the Mobile AI Agents setup commands from the app project:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+npx mobile-ai-agents mcp setup --client <claude|cursor|windsurf|codex>
+npx mobile-ai-agents mcp config init \
+  --app-id com.example.app \
+  --apk app/build/outputs/apk/debug/app-debug.apk \
+  --flow "Launch app|Complete the primary flow|Verify success"
+npx mobile-ai-agents mcp config validate
+```
+
+The setup command preserves existing client settings and is safe to repeat. See `docs/android-device-setup.md` for configuration fields, JSON output, and troubleshooting.
+
 Install Mobile MCP in your AI tool:
 
 ```json

package/templates/android-device-config.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "platform": "android",
+  "appId": "com.example.app",
+  "apkPath": "app/build/outputs/apk/debug/app-debug.apk",
+  "device": "auto",
+  "flow": [
+    "Launch app",
+    "Verify the initial screen"
+  ],
+  "timeouts": {
+    "bootMs": 120000,
+    "actionMs": 15000
+  },
+  "evidenceDir": ".mobile-ai-agents/evidence"
+}