Devilge

io.github.Yercko由 GitHub 账号 Yercko 发布v0.2.3更新于 Oct 24, 2026

Android/KMM MCP server: logcat, ADB device control, Compose previews, network, Maestro flows.

概览

AI 生成的概览

面向 Android/KMM 开发的 MCP 服务器,让助理构建、安装、操作并观察开发机上的应用。

可以做什么
查看项目结构与 Compose 预览,并运行任意 Gradle 任务、解析编译与测试错误。列出设备、读取 logcat、应用错误与网络请求。操作运行中的应用:点击、输入文字、按键、滑动、截图与导出 UI。按文字或资源 ID 定位控件并等待界面就绪。启动、强制停止、清除数据、安装 APK 与运行 instrumented 测试。用 Maestro YAML 流程重放导航,并可批量串联多个工具调用。
适用场景
适合正在开发 Android 或 KMM 应用、希望 AI 助理直接构建、安装、启动并操作开发机或模拟器上应用的开发者。需要反复查看 logcat、抓取错误与网络请求,或重放固定 UI 导航流程时尤其有用。
运行要求
在本机以 npm 包运行,需要 Node.js,并需安装 Android SDK 的 adb 与可用的设备或模拟器。必须将 DEVILGE_ANDROID_PROJECT_ROOT 设为项目绝对路径;可选 DEVILGE_DEFAULT_DEVICE_SERIAL、DEVILGE_MAESTRO_BIN_PATH 等变量。Maestro 流程工具需另装 Maestro,否则会返回未安装。
安装前请注意
服务器提供会改变状态的工具:输入自动化、安装 APK、清除应用数据与强制停止,且不检查目标包是否为前台应用,官方建议只连接开发用模拟器或已清空的测试机。Maestro 流程中的 runScript 块默认被拒绝,除非设置 DEVILGE_ALLOW_FLOW_SCRIPTS。网络请求输出会遮蔽敏感标头,但流程参数可能含账号密码。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Devilge,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

devilge

Model Context Protocol (MCP) server that lets an AI assistant — typically Claude — develop, drive, and observe an Android / KMM app end-to-end.

devilge exposes 33 tools that cover the full inner loop: read the project, build it, install it, launch it, drive its UI, capture errors and network traffic, run tests. Anything an LLM coding agent would otherwise have to ask the user to do manually.

[devilge demo]

What's inside

CategoryToolsPurpose
Device read (8)list_devices, get_logcat, get_app_errors, inspect_packages, resize_logcat_buffer, get_network_calls, get_compose_preview_source, list_compose_previewsObserve device + project state
Project static (3)get_project_structure, get_compose_previews_tree, run_gradle_task (the latter wraps build-result parsers for kotlinc/javac/ksp errors, JUnit XML, Lint XML)Inspect Gradle/KMM project + run any Gradle task
Device drive (7)take_screenshot, dump_ui, input_tap, input_text, input_key, input_swipe, set_input_visualizationManipulate the running app
Locators + waits (6)tap_text, tap_resource_id, set_text, wait_for_text, wait_for_resource_id, wait_for_idleSemantic UI navigation, no coordinate magic
Lifecycle (5)launch_app, force_stop_app, clear_app_data, install_apk, run_instrumented_testsCold-start app, run Espresso tests, fast install
Maestro flows (optional) (3)run_maestro_flow, list_maestro_flows, validate_maestro_flowReusable YAML flows for recurring navigation
Composition (1)batchChain multiple devilge tools in one round trip

215 unit tests in Vitest, all green. Strict TypeScript (strict, noUncheckedIndexedAccess).

Batching for fewer permission prompts

Hosts that confirm every tool call (Claude Desktop, Cowork) can become noisy when the agent walks through multi-step UI flows. devilge_batch collapses a sequence into a single MCP call so the user approves once for the whole sequence.

jsonc
// Tap "Settings", wait, screenshot, tap a row, screenshot — one approval.{  "actions": [    { "name": "devilge_tap_text",       "input": { "text": "Settings" } },    { "name": "devilge_wait_for_idle",  "input": { "timeoutMs": 5000 } },    { "name": "devilge_take_screenshot" },    { "name": "devilge_tap_text",       "input": { "text": "Wallpaper & style" } },    { "name": "devilge_take_screenshot" }  ]}

Rules: capped at 20 actions per call; cannot be nested; cannot include destructive tools (devilge_clear_app_data, devilge_install_apk) — those always require their own dedicated prompt; stops on the first error and reports which step failed.

All tools also expose MCP annotations (readOnlyHint, idempotentHint, destructiveHint, openWorldHint). Hosts that respect annotations can auto-approve safe reads and prompt only on state-changing tools.

Architecture

Clean / hexagonal layering, every concern replaceable in isolation:

src/├── config/                 # Config loading, structured logger, typed errors├── domain/│   ├── entities/           # Pure data types│   └── ports/              # Interfaces the application talks to├── application/            # Use cases — orchestrate ports, no IO of their own├── infrastructure/│   ├── adb/                # AdbAdapter, AdbAppController, runners, parsers│   ├── build/              # Gradle adapter + parsers (compile errors, JUnit, Lint)│   ├── maestro/            # Optional Maestro adapter + YAML validator│   ├── network/            # Ktor logcat parser + header sanitizer│   ├── scanners/           # ComposePreviewScanner, ProjectScanner, FileWalker│   └── security/           # PathValidator, CommandSanitizer└── presentation/    └── tools/              # MCP tool definitions (Zod schemas + handlers)

src/server.ts is the composition root: it constructs every concrete dependency and wires them into an McpServer. Nothing else in the codebase performs construction.

Security model

devilge runs on a developer's machine, exposes mutating tools to an LLM, and shells out to ADB and (optionally) Gradle / Maestro. It assumes the operator connects only to a dev emulator or wiped test device, never a personal device with logged-in apps.

  • Project sandbox. All filesystem reads/writes resolve, after symlink resolution, to paths inside DEVILGE_ANDROID_PROJECT_ROOT or the configured outputs / flows roots. Any escape throws SecurityError.
  • No shell. Every external process (adb, gradlew, maestro) is spawned with shell: false and an argv array. Arguments are never concatenated into strings.
  • Strict argument allowlists. Device serials, logcat tags, package names, activity names, deep links, Gradle tasks, Maestro flow names and env-var keys all pass through CommandSanitizer regex allowlists before reaching argv.
  • Resource caps. Logcat capped (5000 line ceiling), ADB stdout cap 8 MiB, Gradle output cap 256 KiB ring buffer, file scans bounded, screenshot timeout 15 s, instrumented-test timeout 30 min default cap.
  • Symlinks ignored. Walkers never follow symlinks.
  • Logs go to stderr only. Stdout is reserved for the MCP JSON-RPC transport.
  • Errors are sanitized. Only DevilgeError subclasses surface their messages. Unexpected exceptions become an opaque INTERNAL_ERROR.
  • Header redaction. Authorization, Cookie, Set-Cookie, X-API-Key and other well-known sensitive headers are redacted from get_network_calls output.
  • Maestro runScript: denied by default. YAML flows containing runScript: blocks (which execute JS) are rejected unless the operator explicitly sets DEVILGE_ALLOW_FLOW_SCRIPTS=true.
  • No frontmost-app check. devilge does NOT verify that the targeted package matches the device's foreground app. That check is a deployment concern — keep your dev device clean.

The MVP does include write tools (input automation, app install, data wipe, force-stop). These are gated to a dev-only device by operator policy, not by server logic.

Setup

bash
cd devilgenpm installcp .env.example .env# edit .env with your project's absolute pathnpm run build

Run the tests:

bash
npm test

Verify the build:

bash
npm run typecheck    # static type-check (no emit)npm run build        # emit dist/npm run lint         # eslint

Connecting to Claude Desktop

Add an entry to your claude_desktop_config.json (path varies by OS):

json
{  "mcpServers": {    "devilge": {      "command": "node",      "args": ["/absolute/path/to/devilge/dist/index.js"],      "env": {        "DEVILGE_ANDROID_PROJECT_ROOT": "/absolute/path/to/your/android/project",        "DEVILGE_KTOR_LOG_TAG": "HttpClient"      }    }  }}

Restart Claude Desktop. The 33 tools should appear in the tool picker.

Local smoke test (MCP Inspector)

bash
DEVILGE_ANDROID_PROJECT_ROOT=/absolute/path/to/your/android/project \DEVILGE_KTOR_LOG_TAG=HttpClient \npx --yes @modelcontextprotocol/inspector \  node dist/index.js

Configuration reference

VariableRequiredDefaultDescription
DEVILGE_ANDROID_PROJECT_ROOT✅—Absolute path to the Android/KMM project. All file reads are sandboxed under this directory.
DEVILGE_ADB_PATHadb (from PATH)Absolute path to the adb binary. Pinning is recommended.
DEVILGE_DEFAULT_DEVICE_SERIAL—Default serial used when a tool call omits it. Useful when several devices are attached.
DEVILGE_LOGCAT_MAX_LINES500Default cap for get_logcat. Hard upper bound: 5000.
DEVILGE_LOG_LEVELinfoOne of error, warn, info, debug.
DEVILGE_KTOR_LOG_TAGHttpClientLogcat tag the HTTP-client logger writes under. Use HttpClient for Ktor (default), OkHttp for Retrofit/OkHttp, or whatever your custom logger uses.
DEVILGE_HTTP_LOG_FORMATautoWhich parser(s) to apply. ktor, okhttp, or auto (tries both).
DEVILGE_OUTPUTS_ROOT<project>/.devilge-outputs/Where screenshots / UI dumps land. Add to .gitignore.
DEVILGE_FLOWS_ROOT<project>/devilge-flows/Where Maestro YAML flows live.
DEVILGE_MAESTRO_BIN_PATHauto-detected from PATHAbsolute path to the maestro binary. Optional — Maestro tools degrade gracefully when missing.
DEVILGE_ALLOW_FLOW_SCRIPTSfalseSet to true to allow runScript: blocks inside Maestro YAML. Off for safety.

Optional integrations

Maestro (flows)

Maestro is optional. Without it installed, every other devilge tool keeps working. The three flow tools (run_maestro_flow, list_maestro_flows, validate_maestro_flow) register unconditionally and return MAESTRO_NOT_INSTALLED when the binary isn't found.

To enable:

bash
brew tap mobile-dev-inc/tapbrew install maestro
# orcurl -Ls "https://get.maestro.mobile.dev" | bash

Restart the inspector. Flows go in <project>/devilge-flows/<name>.yaml. Example:

yaml
appId: com.example.your.app---- launchApp:    clearState: true- tapOn: "Email"- inputText: ${EMAIL}- tapOn: "Password"- inputText: ${PASSWORD}- tapOn: "Sign in"- assertVisible: "Home"

Then:

json
{  "name": "login_flow",  "params": { "EMAIL": "[email protected]", "PASSWORD": "..." }}

MAESTRO_DISABLE_ANALYTICS=true is injected automatically. runScript: blocks are denied unless you opt in.

Headless Compose preview rendering (recipe, no devilge tool)

You can render @Preview Composables to PNG without launching the full app. devilge does NOT add a dedicated tool for this — the existing run_gradle_task plus the official Google plugin cover it cleanly, and adding a wrapper would make us depend on Gradle conventions that vary by project.

This is completely optional: if you don't add the plugin, devilge runs unchanged. You only lose this specific workflow.

To enable in your project, add to your Compose module's build.gradle.kts:

kotlin
plugins {    // existing plugins...    id("com.android.compose.screenshot") version "0.0.1-alpha10"}
android {    experimentalProperties["android.experimental.enableScreenshotTest"] = true}

And in gradle/libs.versions.toml:

toml
[plugins]composeScreenshot = { id = "com.android.compose.screenshot", version = "0.0.1-alpha10" }

Once the plugin is in place, render previews from the LLM via the existing tool:

json
devilge_run_gradle_task {  "task": ":composeApp:validateDebugScreenshotTest"}

The PNGs land under composeApp/build/outputs/screenshotTest/.... Claude can then read them via its Read tool to verify visual output without installing the app.

Recommended inner-loop workflow

1. run_gradle_task ":composeApp:assembleDebug"   # build once at start2. install_apk { "module": ":composeApp" }       # ~5-8 s vs Gradle's 30-60 s3. launch_app { "packageName": "...", "clean": true }4. tap_text / set_text / wait_for_text           # navigate to the screen5. take_screenshot                               # confirm visual state6. get_app_errors { "followMs": 10000 }          # capture errors as they happen7. get_network_calls                             # verify HTTP requests8. on bug → edit code → back to step 1 (Gradle is incremental, fast)

For recurring navigation paths (login, search, etc.), capture once as a Maestro flow and replay with one tool call.

Backlog (not committed, lowest priority)

  • Compose Live Edit MCP — true HMR for Android Compose. Major project (~2-3 months MVP, JVMTI agent + bytecode transformation + protocol). Waiting for JetBrains' Compose Hot Reload to land for Android first; the wrapper would be ~1-2 weeks.
  • pull_room_database — pull Room SQLite from device, expose readonly queries. Useful for inspecting cached state.
  • pull_anr_traces + deobfuscate_stacktrace — diagnose runtime hangs and ProGuard-mapped release crashes.
  • dumpsys_meminfo / dumpsys_gfxinfo / measure_cold_start — runtime performance metrics.
  • describe_compose_codebase — structural map of the project (data classes, XML resources, color literal frequencies, composables) so the LLM doesn't have to grep at session start. Considered, deferred until proven necessary in real use.

License

MIT

来源:README.md,提交 17d8b50

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.2.3最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分