android-dev
Build, run, inspect, and lightly automate Android apps with the android-emulator MCP tools.
- License 许可
- Apache-2.0
- 所属仓库
- zai-org/ZCode
- 最近更新
- 2026-11-13
- Stars
- ★ 8.7k
- Forks
- 2.7k
01 前言 Front Matter
- name
- android-dev
- description
- Build, run, inspect, and lightly automate Android apps with the android-emulator MCP tools.
02 资源文件 1
- 参考文档INSTALL_ENVIRONMENT.md13.0 KB
03 SKILL.md 正文
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
- Call
mcp__android_emulator__android_preflightfirst. - If the required environment is not ready, followINSTALL_ENVIRONMENT.mdbefore 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. - 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_apprefuses to overwrite generated files by default; only passoverwrite: trueafter explicit user confirmation.- Read
warningsin the discovery result before building and repair missinggradle.properties,local.properties, or Gradle wrapper issues.
- If no Android project exists and the user wants a new app, call
- Build and launch with
mcp__android_emulator__android_build_and_run.- Pass
module,variant, orapplicationIdwhen discovery is ambiguous. - Use a selected
serialwhen the user wants a specific USB device or emulator. Usemcp__android_emulator__android_start_emulatoronly when a new GUI emulator is needed, then pass its returnedserialto follow-up tools. - Read the returned
outputfirst for compile errors; use the returned log path only when more detail is needed.
- Pass
- Verify the app visually with
mcp__android_emulator__android_screenshot. - For runtime checks, use
mcp__android_emulator__android_open_url,mcp__android_emulator__android_launch_app,mcp__android_emulator__android_terminate_app, andmcp__android_emulator__android_logs. - For UI automation, call
mcp__android_emulator__android_ui_statusfirst.- Prefer
mcp__android_emulator__android_ui_describeormcp__android_emulator__android_ui_resolvebefore tapping coordinates. mcp__android_emulator__android_ui_tap,mcp__android_emulator__android_ui_swipe,mcp__android_emulator__android_ui_type_text, andmcp__android_emulator__android_ui_keyeventuse ADB/UI Automator based backends.- If UI automation is unavailable, continue with build/run/screenshot checks and say UI automation is unavailable.
- Prefer
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_preflightis a pure diagnostic check. UseINSTALL_ENVIRONMENT.mdfor guided environment setup when it reports missing dependencies.- The target MCP tools accept
serialfor a specific USB device or emulator andavdfor the fallback emulator to start only when no target is ready.mcp__android_emulator__android_start_emulatorstarts a new GUI emulator and does not reuse existing targets. - Keep emulator interactions through MCP tools instead of raw
adb/emulatorcommands unless a tool does not cover the operation. mcp__android_emulator__android_create_appgenerates a minimal Kotlin + Jetpack Compose app suitable for model-driven iteration.mcp__android_emulator__android_build_apponly builds.mcp__android_emulator__android_build_and_runbuilds, 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.gradleorsettings.gradle.kts- root
build.gradleorbuild.gradle.kts app/build.gradleorapp/build.gradle.ktsgradle.propertieswithandroid.useAndroidX=truelocal.propertieswithsdk.dir=<Android SDK path>when the SDK is not otherwise discoverable- a Gradle wrapper (
gradlew/gradlew.bat) orgradleavailable onPATH
Build Troubleshooting
- If Gradle reports
android.useAndroidX property is not enabled, create or updategradle.propertieswithandroid.useAndroidX=true. - If
android_preflightreportsGradleasnot found, follow the quick Gradle fix inINSTALL_ENVIRONMENT.md; do not reinstall the Android SDK when Gradle is the only missing check. - If
android_preflightreports no AVDs but a USB device is ready, continue by passing that deviceserialto target tools. - If Gradle cannot find the Android SDK, create
local.propertiesin the Android Gradle root withsdk.dir=<Android SDK path>. - If
./gradleworgradlew.batis missing, install Gradle and rungradle wrapper --gradle-version 8.9, or letandroid_build_appattempt wrapper generation whengradleis available. - If
sdkmanageroravdmanagercannot find Java after installing Homebrewopenjdk@<configured JDK major>, export the matchingJAVA_HOMEfromINSTALL_ENVIRONMENT.mdand 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
defaultimage first and retry the exactsdkmanager --installcommand with a longer timeout before switching to largergoogle_apisimages.
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.
04 同仓库更多 Skills
plugin-mcp-ping
E2E workspace Plugin skill marker
e2e-ext-compat-plain
PLM-EXT-STORE fixture skill for e2e-ext-compat-plain.
e2e-ext-compat-ok
PLM-EXT-STORE fixture skill for e2e-ext-compat-ok.
e2e-ext-compat-installed
PLM-EXT-STORE fixture skill for e2e-ext-compat-installed.
e2e-ext-compat-future
PLM-EXT-STORE fixture skill for e2e-ext-compat-future.
e2e-store-skill-b
E2E store fixture skill b