devilge

devilge

Model Context Protocol（MCP）服务，让 AI 助手（通常是 Claude）能够端到端地开发、驱动和观察 Android / KMM 应用。

devilge 提供 33 个工具，覆盖完整的内部开发循环：读取项目、构建、安装、启动、驱动 UI、捕获错误和网络流量，以及运行测试。编码 Agent 原本需要用户手动完成的所有操作，都可以通过这些工具完成。

包含内容

类别	工具	用途
设备读取（8）	list_devices、get_logcat、get_app_errors、inspect_packages、resize_logcat_buffer、get_network_calls、get_compose_preview_source、list_compose_previews	观察设备和项目状态
项目静态检查（3）	get_project_structure、get_compose_previews_tree、run_gradle_task（后者封装了用于解析 kotlinc/javac/ksp 错误、JUnit XML 和 Lint XML 的构建结果解析器）	检查 Gradle/KMM 项目并运行任意 Gradle 任务
设备驱动（7）	take_screenshot、dump_ui、input_tap、input_text、input_key、input_swipe、set_input_visualization	操作正在运行的应用
定位器和等待（6）	tap_text、tap_resource_id、set_text、wait_for_text、wait_for_resource_id、wait_for_idle	通过语义化 UI 导航，无需猜测坐标
生命周期（5）	launch_app、force_stop_app、clear_app_data、install_apk、run_instrumented_tests	冷启动应用、运行 Espresso 测试、快速安装
Maestro 流程（可选）（3）	run_maestro_flow、list_maestro_flows、validate_maestro_flow	用于重复导航的可复用 YAML 流程
组合（1）	batch	在一次往返中串联多个 devilge 工具

Vitest 中有 215 个单元测试，全部通过。使用严格的 TypeScript 配置（strict、noUncheckedIndexedAccess）。

批量调用，减少权限提示

对于会确认每次工具调用的宿主（Claude Desktop、Cowork），当 Agent 执行多步 UI 流程时，确认提示可能会很频繁。devilge_batch 会将一系列操作合并为一次 MCP 调用，让用户只需为整个序列批准一次。

// 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" }
  ]
}

规则：每次调用最多 20 个操作；不能嵌套；不能包含破坏性工具（devilge_clear_app_data、devilge_install_apk）——这些工具始终需要单独的专用提示；遇到第一个错误时停止，并报告失败步骤。

所有工具还会公开 MCP annotations（readOnlyHint、idempotentHint、destructiveHint、openWorldHint）。遵循这些注解的宿主可以自动批准安全的读取操作，只在会更改状态的工具上提示确认。

架构

采用整洁 / 六边形分层，每项关注点都可独立替换：

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 是组合根：它会构建每个具体依赖，并将它们连接到 McpServer。代码库中的其他部分都不负责构建依赖。

安全模型

devilge 运行在开发者的机器上，会向大模型暴露可执行修改的工具，并调用 ADB 以及（可选的）Gradle / Maestro。它假设操作者只连接到开发模拟器或已清除数据的测试设备，绝不会连接到已登录应用的个人设备。

• 项目沙箱。 解析符号链接后，所有文件系统读写路径都必须位于 DEVILGE_ANDROID_PROJECT_ROOT 或已配置的输出目录 / 流程目录中。任何越界操作都会抛出 SecurityError。
• 不使用 Shell。 每个外部进程（adb、gradlew、maestro）都会以 shell: false 和 argv 数组启动。参数绝不会拼接成字符串。
• 严格的参数允许列表。 设备序列号、logcat 标签、包名、Activity 名称、深层链接、Gradle 任务、Maestro 流程名称和环境变量键都会先通过 CommandSanitizer 的正则表达式允许列表检查，再传入 argv。
• 资源上限。 Logcat 最多 5000 行，ADB 标准输出上限为 8 MiB，Gradle 输出环形缓冲区上限为 256 KiB，文件扫描范围受限，截图超时为 15 秒，插桩测试默认超时上限为 30 分钟。
• 忽略符号链接。 遍历程序绝不会跟随符号链接。
• 日志仅输出到 stderr。 Stdout 专用于 MCP JSON-RPC 传输。
• 错误经过净化。 只有 DevilgeError 子类的错误消息会对外显示。意外异常会转换为不透明的 INTERNAL_ERROR。
• 请求头脱敏。 Authorization、Cookie、Set-Cookie、X-API-Key 及其他常见敏感请求头会从 get_network_calls 的输出中脱敏。
• 默认禁止 Maestro runScript:。 包含 runScript: 代码块（用于执行 JS）的 YAML 流程会被拒绝，除非操作者显式设置 DEVILGE_ALLOW_FLOW_SCRIPTS=true。
• 不检查前台应用。 devilge 不会验证目标包名是否与设备的前台应用匹配。这项检查属于部署方面的职责——请保持开发设备干净。

MVP 确实包含写入工具（输入自动化、应用安装、数据清除、强制停止）。这些工具是否仅用于开发设备，由操作者策略决定，而非服务端逻辑。

设置

cd devilge
npm install
cp .env.example .env
# edit .env with your project's absolute path
npm run build

运行测试：

npm test

验证构建：

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

连接到 Claude Desktop

在 claude_desktop_config.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"
      }
    }
  }
}

重启 Claude Desktop。工具选择器中应会显示 33 个工具。

本地冒烟测试（MCP Inspector）

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

配置参考

变量	必填	默认值	描述
DEVILGE_ANDROID_PROJECT_ROOT	✅	—	Android/KMM 项目的绝对路径。所有文件读取都受此目录的沙箱限制。
DEVILGE_ADB_PATH		adb（来自 PATH）	adb 二进制文件的绝对路径。建议固定路径。
DEVILGE_DEFAULT_DEVICE_SERIAL		—	工具调用未提供 serial 时使用的默认值。连接了多个设备时很有用。
DEVILGE_LOGCAT_MAX_LINES		500	get_logcat 的默认上限。硬性上限：5000。
DEVILGE_LOG_LEVEL		info	可选值：error、warn、info、debug。
DEVILGE_KTOR_LOG_TAG		HttpClient	HTTP 客户端日志记录器使用的 logcat 标签。Ktor 使用 HttpClient（默认值），Retrofit/OkHttp 使用 OkHttp，也可以使用自定义日志记录器所用的标签。
DEVILGE_HTTP_LOG_FORMAT		auto	要应用的解析器。可选值：ktor、okhttp 或 auto（尝试两者）。
DEVILGE_OUTPUTS_ROOT		<project>/.devilge-outputs/	截图 / UI 转储的保存位置。请将其添加到 .gitignore。
DEVILGE_FLOWS_ROOT		<project>/devilge-flows/	Maestro YAML 流程的存放位置。
DEVILGE_MAESTRO_BIN_PATH		从 PATH 自动检测	maestro 二进制文件的绝对路径。可选——缺少 Maestro 时，相关工具会正常降级。
DEVILGE_ALLOW_FLOW_SCRIPTS		false	设置为 true 可允许 Maestro YAML 中包含 runScript: 代码块。出于安全考虑，默认关闭。

可选集成

Maestro（flows）

Maestro 是可选的。未安装时，其他所有 devilge 工具仍可正常工作。三个流程工具（run_maestro_flow、list_maestro_flows、validate_maestro_flow）会始终注册，并在找不到二进制文件时返回 MAESTRO_NOT_INSTALLED。

启用方法：

brew tap mobile-dev-inc/tap
brew install maestro

# or
curl -Ls "https://get.maestro.mobile.dev" | bash

重启检查器。流程文件放在 <project>/devilge-flows/<name>.yaml 中。示例：

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

然后：

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

系统会自动注入 MAESTRO_DISABLE_ANALYTICS=true。除非你选择启用，否则会禁止使用 runScript: 块。

无头 Compose 预览渲染（操作指南，不是 devilge 工具）

你可以在不启动完整应用的情况下，将 @Preview Composables 渲染为 PNG。devilge 不会为此添加专用工具——现有的 run_gradle_task 和 Google 官方插件即可很好地完成这项工作，添加包装器则会让我们依赖因项目而异的 Gradle 约定。

这完全是可选的：如果你不添加插件，devilge 会照常运行。你只会失去这个特定工作流。

如要在项目中启用，请将以下内容添加到 Compose 模块的 build.gradle.kts 中：

plugins {
    // existing plugins...
    id("com.android.compose.screenshot") version "0.0.1-alpha10"
}

android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}

并添加到 gradle/libs.versions.toml 中：

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

配置好插件后，通过现有工具让 LLM 渲染预览：

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

PNG 文件会生成在 composeApp/build/outputs/screenshotTest/... 下。随后，Claude 可以通过其 Read 工具读取这些文件，在不安装应用的情况下检查视觉输出。

推荐的内循环工作流

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

对于经常使用的导航路径（登录、搜索等），只需录制一次 Maestro 流程，之后即可通过一次工具调用重放。

待办事项（尚未提交，优先级最低）

• Compose Live Edit MCP — 为 Android Compose 提供真正的 HMR。这是一个大型项目（MVP 约需 2-3 个月，涉及 JVMTI Agent、字节码转换和协议）。目前等待 JetBrains 先为 Android 发布 Compose Hot Reload；届时包装器约需 1-2 周完成。
• pull_room_database — 从设备拉取 Room SQLite 数据库，并提供只读查询。适用于检查缓存状态。
• pull_anr_traces + deobfuscate_stacktrace — 诊断运行时卡死和经 ProGuard 映射的发布版崩溃。
• dumpsys_meminfo / dumpsys_gfxinfo / measure_cold_start — 运行时性能指标。
• describe_compose_codebase — 提供项目的结构图（数据类、XML 资源、颜色字面值频率、composables），免得 LLM 在会话开始时执行 grep。已考虑过，暂缓，待真实使用证明有此需要后再决定。

许可证

MIT