devilge

devilge

AI アシスタント（通常は Claude）が Android／KMM アプリをエンドツーエンドで開発、操作、監視できるようにする Model Context Protocol（MCP）サーバーです。

devilge は、完全な内部ループをカバーする 33 個のツールを公開します。プロジェクトの読み込み、ビルド、インストール、起動、UI の操作、エラーやネットワークトラフィックの取得、テストの実行ができます。LLM コーディングエージェントが、通常ならユーザーに手動で依頼する必要がある作業をすべて実行します。

内容

カテゴリ	ツール	目的
デバイスの読み取り（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 ツールを 1 回の往復で連鎖実行

Vitest の単体テスト 215 件はすべて成功しています。TypeScript の厳格な設定（strict、noUncheckedIndexedAccess）を使用しています。

許可確認を減らすバッチ処理

ツール呼び出しのたびに確認を求めるホスト（Claude Desktop、Cowork など）では、エージェントが複数ステップの UI フローを進める際に確認が煩雑になることがあります。devilge_batch を使うと、一連の処理を 1 回の MCP 呼び出しにまとめられるため、ユーザーはシーケンス全体を 1 回で承認できます。

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

ルール：1 回の呼び出しにつき最大 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 は開発者のマシン上で動作し、LLM に変更を加えるツールを公開して、ADB および（任意で）Gradle / Maestro を起動します。操作者が接続するのは開発用エミュレーターまたはデータ消去済みのテスト端末のみであり、ログイン済みアプリのある個人端末には接続しないことを前提としています。

• プロジェクトのサンドボックス。 シンボリックリンクを解決した後のすべてのファイルシステムの読み書き先は、DEVILGE_ANDROID_PROJECT_ROOT または設定された出力ルート／フロールート内のパスになります。範囲外へのアクセスは SecurityError をスローします。
• シェル不使用。 すべての外部プロセス（adb、gradlew、maestro）は、shell: false と argv 配列を使って起動します。引数を文字列に連結することはありません。
• 厳格な引数許可リスト。 デバイスのシリアル番号、logcat タグ、パッケージ名、アクティビティ名、ディープリンク、Gradle タスク、Maestro フロー名、環境変数キーはすべて、argv に渡される前に CommandSanitizer の正規表現許可リストを通過します。
• リソース上限。 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: はデフォルトで拒否。 JS を実行する runScript: ブロックを含む 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 にエントリーを追加します（パスは OS によって異なります）：

{
  "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 が見つからない場合、Maestro ツールは機能を縮小して動作します。
DEVILGE_ALLOW_FLOW_SCRIPTS		false	Maestro YAML 内の runScript: ブロックを許可するには true に設定します。安全のため、デフォルトでは無効です。

任意の連携

Maestro（フロー）

Maestro は任意です。インストールされていなくても、ほかの devilge ツールはすべて引き続き動作します。3 つのフローツール（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 Composable を 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 フローとして一度記録しておけば、ツールを 1 回呼び出すだけで再生できます。

バックログ（未コミット、優先度最低）

• Compose Live Edit MCP — Android Compose 向けの本格的な HMR です。大規模なプロジェクトです（MVP まで約 2～3 か月、JVMTI エージェント＋バイトコード変換＋プロトコル）。まず JetBrains の Compose Hot Reload が Android に対応するのを待っています。その後、ラッパーの開発には約 1～2 週間かかる見込みです。
• pull_room_database — デバイスから Room SQLite を取得し、読み取り専用クエリを提供します。キャッシュされた状態の確認に役立ちます。
• pull_anr_traces と deobfuscate_stacktrace — 実行時のハングや、ProGuard でマッピングされたリリース版のクラッシュを診断します。
• dumpsys_meminfo / dumpsys_gfxinfo / measure_cold_start — 実行時のパフォーマンス指標です。
• describe_compose_codebase — プロジェクトの構造マップ（データクラス、XML リソース、色リテラルの出現頻度、Composable）を提供し、セッション開始時に LLM が grep する手間を省きます。検討しましたが、実際の利用で必要性が確認されるまで保留しています。

ライセンス

MIT