zai-org/zcode/android-dev

Android Dev

Use this skill when the user wants you to create, modify, build, run, debug, screenshot, or inspect an Android app in the desktop Android Emulator or on a USB-connected Android device.

ZCode Tool Names

This skill assumes the MCP server is configured in zcode as android_emulator. In zcode, MCP tools are exposed to the model as mcp__android_emulator__<tool>.

If the server is configured with a different name, use the corresponding visible mcp__<server>__... tool names from the active zcode tool list.

Default Workflow

1. Call mcp__android_emulator__android_preflight first.

• If the required environment is not ready, follow INSTALL_ENVIRONMENT.md before continuing. Missing emulator-only checks do not block a selected ready USB device target.
• Environment setup is done with the fixed macOS shell or Windows PowerShell procedure in that file; do not improvise unrelated install commands.
• Do not accept Android SDK licenses, enter passwords, wipe emulator data, or delete AVDs on the user's behalf. Stop and ask the user for those cases.

1. Discover the project with mcp__android_emulator__android_discover_project.

• If no Android project exists and the user wants a new app, call mcp__android_emulator__android_create_app.
• Prefer editing Kotlin/Compose files directly after project creation.
• mcp__android_emulator__android_create_app refuses to overwrite generated files by default; only pass overwrite: true after explicit user confirmation.
• Read warnings in the discovery result before building and repair missing gradle.properties, local.properties, or Gradle wrapper issues.

1. Build and launch with mcp__android_emulator__android_build_and_run.

• Pass module, variant, or applicationId when discovery is ambiguous.
• Use a selected serial when the user wants a specific USB device or emulator. Use mcp__android_emulator__android_start_emulator only when a new GUI emulator is needed, then pass its returned serial to follow-up tools.
• Read the returned output first for compile errors; use the returned log path only when more detail is needed.

1. Verify the app visually with mcp__android_emulator__android_screenshot.
2. For runtime checks, use mcp__android_emulator__android_open_url, mcp__android_emulator__android_launch_app, mcp__android_emulator__android_terminate_app, and mcp__android_emulator__android_logs.
3. For UI automation, call mcp__android_emulator__android_ui_status first.

• Prefer mcp__android_emulator__android_ui_describe or mcp__android_emulator__android_ui_resolve before tapping coordinates.
• mcp__android_emulator__android_ui_tap, mcp__android_emulator__android_ui_swipe, mcp__android_emulator__android_ui_type_text, and mcp__android_emulator__android_ui_keyevent use ADB/UI Automator based backends.
• If UI automation is unavailable, continue with build/run/screenshot checks and say UI automation is unavailable.

Tool Notes

• This MVP intentionally uses Android Emulator's own desktop window for rendering. Do not create or expect a custom emulator window.
• mcp__android_emulator__android_preflight is a pure diagnostic check. Use INSTALL_ENVIRONMENT.md for guided environment setup when it reports missing dependencies.
• The target MCP tools accept serial for a specific USB device or emulator and avd for the fallback emulator to start only when no target is ready. mcp__android_emulator__android_start_emulator starts a new GUI emulator and does not reuse existing targets.
• Keep emulator interactions through MCP tools instead of raw adb/emulator commands unless a tool does not cover the operation.
• mcp__android_emulator__android_create_app generates a minimal Kotlin + Jetpack Compose app suitable for model-driven iteration.
• mcp__android_emulator__android_build_app only builds. mcp__android_emulator__android_build_and_run builds, reuses the selected Android target by serial or starts a GUI emulator when needed, installs, and launches the app.
• Android SDK path, default AVD, API level, build-tools version, system image variant/ABI, and JDK major version come from plugin user config and are exposed to the MCP server as ANDROID_PLUGIN_* environment variables.

Project Requirements

When creating or repairing a project manually, make sure these files exist before building:

• settings.gradle or settings.gradle.kts
• root build.gradle or build.gradle.kts
• app/build.gradle or app/build.gradle.kts
• gradle.properties with android.useAndroidX=true
• local.properties with sdk.dir=<Android SDK path> when the SDK is not otherwise discoverable
• a Gradle wrapper (gradlew / gradlew.bat) or gradle available on PATH

Build Troubleshooting

• If Gradle reports android.useAndroidX property is not enabled, create or update gradle.properties with android.useAndroidX=true.
• If android_preflight reports Gradle as not found, follow the quick Gradle fix in INSTALL_ENVIRONMENT.md; do not reinstall the Android SDK when Gradle is the only missing check.
• If android_preflight reports no AVDs but a USB device is ready, continue by passing that device serial to target tools.
• If Gradle cannot find the Android SDK, create local.properties in the Android Gradle root with sdk.dir=<Android SDK path>.
• If ./gradlew or gradlew.bat is missing, install Gradle and run gradle wrapper --gradle-version 8.9, or let android_build_app attempt wrapper generation when gradle is available.
• If sdkmanager or avdmanager cannot find Java after installing Homebrew openjdk@<configured JDK major>, export the matching JAVA_HOME from INSTALL_ENVIRONMENT.md and retry. Use the optional symlink step only after user confirmation.
• On Windows, if SDK package installation fails because Android SDK licenses are not accepted, ask the user for explicit approval before running sdkmanager.bat --licenses, then retry the same package installation command.
• On Windows, if emulator acceleration is unavailable, ask the user to enable virtualization/WHPX or finish Android Emulator driver setup in Android Studio Device Manager, then rerun android_preflight.
• If system image downloads time out, prefer the default image first and retry the exact sdkmanager --install command with a longer timeout before switching to larger google_apis images.

Extension Point

The Android backend is deliberately isolated. P0 uses Android SDK tools, ADB/UI Automator, and Gradle. Future backends can map the same public operations to Android Studio semantic tools, a UI Automator helper APK, Appium/uiautomator2, or another automation bridge without changing the skill workflow.