APK Preview Desktop

Aplicativo Windows para instalar, executar, navegar e inspecionar APKs em um Android Emulator dedicado. A mesma sessão pode ser controlada pela interface PySide6 ou por ferramentas MCP locais usadas pelo Codex.

O projeto não implementa uma máquina virtual Android. Ele controla o Android Emulator oficial e renderiza capturas ADB dentro de uma interface desktop.

Recursos

• descoberta automática do Android SDK no Windows;

• inicialização de AVDs dedicados com prefixo ApkPreview_;

• instalação e atualização de APKs com adb install -r;

• abertura de aplicativos instalados;

• preview atualizado dentro da janela desktop;

• cliques no preview convertidos em coordenadas Android;

• botões Voltar, Início e Recentes;

• perfis de celular e tablet;

• orientação retrato e paisagem;

• tema claro, escuro ou definido pelo sistema;

• captura PNG e inspeção da árvore UI;

• servidor MCP local sem comandos shell arbitrários;

• launcher Windows sem console e ponte nativa para isolamento de DLLs Qt/ADB.

Related MCP server: mobila

Arquitetura

flowchart LR
    UI[Desktop PySide6] --> C[AndroidController]
    MCP[Servidor MCP stdio] --> C
    C --> R[ProcessRunner]
    R --> B[ProcessBridge Windows]
    B --> ADB[adb / emulator]
    ADB --> AVD[AVD ApkPreview_*]
    AVD --> PNG[Capturas e árvore UI]
    PNG --> UI
    PNG --> MCP

AndroidController concentra validação, instalação, navegação e captura. ProcessRunner executa somente binários conhecidos usando listas de argumentos e shell=False. No Windows, ProcessBridge.exe cria uma fronteira limpa entre as DLLs carregadas pelo Qt e as ferramentas do Android SDK.

Requisitos

• Windows 11;

• Python 3.12 ou superior;

• uv;

• JDK 21 para projetos Android que precisem ser compilados;

• Android SDK Platform Tools e Android Emulator;

• imagem Android x86_64 compatível;

• virtualização de hardware habilitada.

O SDK é procurado nesta ordem: ANDROID_HOME, ANDROID_SDK_ROOT, depois %LOCALAPPDATA%\Android\Sdk.

Instalação para desenvolvimento

git clone https://github.com/Famel-svg/apk-preview-desktop.git
cd apk-preview-desktop
uv sync --all-groups

Crie pelo Android Studio um AVD cujo nome comece por ApkPreview_. Exemplo: ApkPreview_Phone_API37.

Executar

uv run apk-preview-desktop

Fluxo básico:

1. selecione o AVD;

2. clique em Iniciar;

3. escolha um arquivo .apk;

4. clique em Instalar APK;

5. selecione o pacote instalado e clique em Abrir app;

6. use o preview, perfis de tela e controles Android.

Servidor MCP

uv run apk-preview-mcp

Plugin portátil: plugins/apk-preview/. Configurações com caminhos absolutos da máquina não fazem parte do repositório.

Gerar executável Windows

.\scripts\build-windows.ps1

Saída: dist/APK Preview Desktop/APK Preview Desktop.exe.

O launcher usa .venv do projeto. Execute uv sync antes de abrir o executável. Artefatos binários não são versionados.

Testes e qualidade

uv run pytest -q
uv run ruff check .
uv run pyright

Estrutura

src/apk_preview/             aplicação, Android e MCP
tests/                       testes automatizados
native/                      launcher e ponte de processos em C#
scripts/                     build Windows
plugins/apk-preview/         plugin MCP portátil
APK_PREVIEW_DESKTOP_SPEC.md  especificação funcional

Segurança

• dispositivos físicos são recusados;

• somente seriais emulator-* confirmados como QEMU são aceitos;

• somente AVDs ApkPreview_* são controlados;

• APK precisa existir localmente e possuir extensão .apk;

• subprocessos não recebem texto shell arbitrário;

• capturas temporárias usam nomes únicos e são removidas;

• stop_session não apaga AVD nem dados;

• credenciais, APKs, executáveis, artefatos e configurações locais são ignorados.

Use apenas APKs próprios ou autorizados. Use dados sintéticos e contas de teste.

Solução de problemas

Android SDK não encontrado

Defina ANDROID_HOME e confirme platform-tools/adb.exe e emulator/emulator.exe.

AVD não aparece

Crie ou renomeie um AVD usando prefixo ApkPreview_.

Erro de DLL do Qt ou console piscando

Recompile com scripts/build-windows.ps1. Launcher e ponte são aplicativos Windows sem console.

Preview não atualiza

Confirme boot concluído e estado device em adb devices -l; clique em Atualizar.

Limitações

• suporte principal: Windows;

• requer Android Emulator oficial;

• não substitui testes instrumentados do APK;

• não contorna autenticação, permissões Android ou proteções do aplicativo;

• executável local depende do ambiente Python sincronizado.

Licença

Nenhuma licença pública definida. Todos os direitos permanecem com o autor.