OpenGL Android開発と自動化のためのMCP

AIコーディングエージェント（Claude Code、Cursorなど）が、UI全体が単一の不透明なOpenGL/Vulkan/Metalサーフェス内に描画されるAndroidアプリ（Cocos2d-x、Unity、Unreal、生のOpenGL、libGDXなど）をテストするためのMCPサーバーです。

これが解決する問題

adb shell uiautomator dumpや、アクセシビリティツリーに基づくすべての自動化ツール（ほとんどのMCPモバイル自動化サーバーを含む）は、ネイティブのAndroidビュー階層（ボタン、ラベル、そのテキストと座標）を検査することで動作します。これは、ネイティブビューで構築された通常のAndroid UIではうまく機能します。

しかし、UI全体を1つのGLSurfaceView内のテクスチャとしてレンダリングするゲームやアプリでは機能しません。アクセシビリティツリーの観点からは、画面上には子要素もラベルも、内部の何かの座標もない、単一の不透明なビューしか存在しません。検査するものは何もありません。実際にどれだけのUIが表示されていても、画面はブラックボックスです。

残された唯一の実際の観測手段はスクリーンショットです。このサーバーは、その事実を通常のケースとして、まれなフォールバックとしてではなく、中心に据えて構築されています。

mobile-mcpとの違い

mobile-next/mobile-mcpは汎用のMCPモバイル自動化サーバーであり、通常のネイティブアプリには良いデフォルトの選択肢です。アクセシビリティツリーを優先し（高速、低コスト、ビジョンモデル不要、画像トークン不要）、ツリーが必要な情報を提供しない場合にのみスクリーンショット+座標にフォールバックします。

OpenGLキャンバスアプリの場合、そのフォールバックはまれなものではなく、毎回機能する唯一の経路です。mobile-mcp-openglはそのケースに特化して構築されており、その結果として2つの異なる設計上の選択を行っています：

1. アクセシビリティツリーの試行は一切行いません。 試しても無駄です。これらのアプリでは常に空で返ってくるため、ここにあるすべてのツールは直接スクリーンショット+ビジョンに進みます。

2. ビジョン分析は、プラグイン可能な別のプロバイダーを経由します（下記参照）。呼び出し元エージェントを実行しているモデルではありません。ゲームに対する機能QAループは、セッションあたり数百回のスクリーンショットチェックに簡単に達する可能性があります。そのすべてをメインのコーディングエージェント自身のビジョンにルーティングすると、実際のコーディング作業に使いたいお金とトークン/コンテキストの両方がかかります。ここでは、スクリーンショットのバイトは呼び出し元エージェントのコンテキストに一切入りません。プロバイダーの短いテキスト回答だけが入ります。

Related MCP server: Android-MCP

なぜ個別のプリミティブではなく、アクション+オブザーブを組み合わせたツールなのか

素朴な設計では、tap、screenshot、askを3つの別々のツールとして公開します。これにより、呼び出し元エージェントはすべての操作に対してマルチステップのループを調整する必要があります：タップ→スクリーンショットを撮る→ビジョンステップに渡す→結果を読む→次に何をするか決定する。それぞれが別々のツール呼び出しであり、別々のターンです。実際のテストロジックではなく調整にトークンを消費し、エージェントがステップを落としたり、順序を間違えたり、呼び出し間で古い状態について推論したりする余地が広がります。

代わりに、このサーバーは組み合わせたツール（tap_and_ask、swipe_and_ask、long_press_and_ask）を公開します。これらはアクションを実行し、少し待って、スクリーンショットを撮り、ビジョンプロバイダーに質問し、1つの短い回答を返します。すべて単一のツール呼び出しです。マルチステップのテストシナリオは、意味のあるチェックごとに約1エージェントターンで済み、3つや4つにはなりません。

このパターンを必要としないテストフローの部分には、単純なscreenshot_ask（観察のみ、アクションなし）と安価な非ビジョンツール（type_text、press_key、logcat_grep）も利用できます。

ツール

必要な情報がすでにログ行にある場合（クラッシュ、独自のデバッグ出力、ネットワークエラー）は、ビジョン呼び出しよりもlogcat_grepを優先してください。無料で正確ですが、ビジョン呼び出しはどちらでもありません。

アニメーションの確認：record_and_ask

単一フレームのツールでは、何かが正しくアニメーションしているかどうかを知ることはできません（強度インジケーターが滑らかに脈動するか、ラベルが飛び上がってフェードアウトするか、スプライトが開始位置に跳ね返るか）。record_and_askは、1つのオプションのアクション（タップまたはスワイプ、またはどちらでもない）を実行し、waitMs待って（tap_and_ask/swipe_and_askのwaitMsと同じ意味 — 最初のフレームの前にUIが反応し始めるまでの時間）、その後intervalMs間隔でframeCount枚のスクリーンショットを撮り、フレームごとに1つの短い回答を返します。呼び出し元エージェントは、N回の個別のスクリーンショット+質問の往復を自分で調整する代わりに、1回のツール呼び出しでタイムラインを取得します。

なぜフレームごとに1回のビジョン呼び出しなのか、すべてのフレームをまとめて1回の呼び出しではないのか。 RunwareのimageCaptionは、文書化された単一のinputImageに加えて、文書化されていないinputImages配列（複数形）を受け入れることが判明しました — APIに対して直接テスト済みです。正確に2枚の画像では問題なく機能します（同じリクエスト内での前後比較は正しく一貫した結果が返りました）。1リクエストで3枚以上の画像の場合、その配列パラメータと手動で合成したサイドバイサイドの「フィルムストリップ」画像の両方が、テストで切り詰められた、または不正な回答を生成しました。小さな7Bビジョンモデルは、1回の呼び出しで視覚+指示の負荷が一定を超えると、どうやら一貫性を失うようです。逐次的な単一画像呼び出し（このツールのアプローチ）は、テストしたどのフレーム数でも信頼性が高く、コストも実質的に高くありません。コストは呼び出し回数ではなく応答長によって支配されるため（下記参照）、N回の短い逐次回答は、1回の長い複数画像回答とほぼ同じか、それ以下のコストになります。独自のプロバイダーが複数画像リクエストをより確実に処理できる場合は、これが明らかに最適化のポイントです — 「独自モデルを使用する」を参照してください。

セットアップ

git clone <this repo>
cd mobile-mcp-opengl
npm install
cp .env.example .env
# edit .env: at minimum set RUNWARE_API_KEY (or switch VISION_PROVIDER, see below)

PATHにadbが必要です（または.envでADB_PATHを設定）。また、実行中/接続済みのデバイスまたはエミュレーターが必要です。複数接続されている場合は、ADB_DEVICE_SERIALを設定してください（adb devicesを参照）。

Claude Codeに登録する

プロジェクトのルートに.mcp.jsonを追加します（このファイルは通常プロジェクトローカルでgit無視されます。通常はマシン固有のパスを指すか、マシン固有の環境変数の上書きを保持するためです）：

{
  "mcpServers": {
    "mobile-opengl": {
      "command": "node",
      "args": ["/absolute/path/to/mobile-mcp-opengl/src/server.js"]
    }
  }
}

Claude Codeはこれをプロジェクト用に自動的に取得します。サーバーはすべての設定を独自の.env（このリポジトリのpackage.jsonの隣）から読み取ります。呼び出し元エージェントはAPIキーを知ったり渡したりする必要は一切ありません。

コストモデル — 長時間のQAセッションを実行する前にこれを読んでください

コストを左右するのは応答長であり、画像サイズではありません。 これはデフォルトのRunware/Qwen2.5-VL-7B-Instructプロバイダーに対して経験的に測定されました。同じ質問を強制的に1語で回答させた場合、360×360から1600×2400（retinaクラス）までの画像サイズで同じコスト（$0.0006）でした。同じ1024×1024の画像で、自由回答の「これを説明してください」というプロンプトでは$0.0013〜0.0019かかりました — 2〜3倍です。これは純粋にモデルがより長い回答を書いたためであり、画像が大きいためではありません。

実際的な影響：

• 送信前にスクリーンショットをダウンサンプリングする必要はありません — このプロバイダーではコストを実質的に削減できず、必要な詳細を失う可能性があります。

• 常に短い回答を強制するように質問を組み立ててください：はい/いいえ、数字、短いラベル、いくつかのフィールドを持つ小さなJSONオブジェクト。このサーバーのすべてのツールは自動的に短い回答の指示を追加しますが、曖昧な自由回答の質問（「何が見えますか？」）は、具体的な質問（「エラーダイアログは表示されていますか？はい/いいえ」）よりも長い回答にモデルを押しやる可能性があります。

適切に構成された短い質問で約$0.0006/呼び出しの場合、500回のQAセッションは約$0.30かかります。同じ量の自由回答の「画面を説明してください」という質問は、その2〜3倍になる可能性があります。

組み込みの支出ガードレール

すべてのビジョン呼び出しは.vision-log.jsonl（JSONL、呼び出しごとに1エントリ：タイムスタンプ、質問、回答、コスト）に記録されます。そのログの上に2つの独立した保護が置かれ、どちらもプロバイダーに依存しません（プロバイダーが報告するcostUsdに基づいて機能します）：

• 呼び出しごとのアラート（VISION_ALERT_USD、デフォルト$0.0015）：単一の呼び出しがこれを超えて返された場合、ツールの応答には[COST ALERT]メモが含まれ、モデルが短い回答の指示を無視した可能性があることを知らせます。これは質問を再構成するためのシグナルであり、黙って受け入れるものではありません。

• 日次上限（VISION_SESSION_CAP_USD、デフォルト$2.00）：今日の累積記録支出がこれに達すると、それ以降のすべてのビジョン呼び出しは（プロバイダーに到達する前に）完全に拒否されます。上限が引き上げられるか、日が変わるまでです。これは暴走ループに対するハードストップであり、単なる警告ではありません。

vision_spend_reportをいつでも呼び出して、デバイスやビジョン呼び出しを行わずに今日の合計を確認できます。

プロバイダーがコストを報告できない場合（下記のopenai-compatibleを参照）、そのプロバイダーからの呼び出しはcostUsd: nullで記録され、アラートをトリガーしたり上限にカウントされたりすることはありません。ガードレールは、可視性のない支出を保護することはできません。

独自モデルを使用する

ビジョン分析はsrc/providers/visionProvider.jsを経由します。これは.envのVISION_PROVIDERから名前でプロバイダーを選択します。組み込みは2つです：

• runware（デフォルト）— Runware.aiのimageCaptionタスクに直接通信し、デフォルトでQwen2.5-VL-7B-Instruct（AIR ID runware:152@2）を使用します。RunwareとOpenRouterは別々のサービスで、別々のAPIキーとモデルカタログを持っています。これはOpenRouterを介さずにRunwareに直接通信します。

• openai-compatible — OpenAIチャット完了ビジョン形式（image_urlコンテンツパーツ）を話すもののための汎用プロバイダーです。OpenRouter、ビジョンモデルを実行するローカルのOllama/LM Studioサーバー、Groq、Together.ai、その他の互換性のあるエンドポイントで動作します。.envでOPENAI_COMPATIBLE_BASE_URL、OPENAI_COMPATIBLE_API_KEY、OPENAI_COMPATIBLE_MODELを設定します。ほとんどのOpenAI互換APIは、固定のドルコストではなくトークン使用量を報告します。このプロバイダーにcostUsdを推定させたい場合は、OPENAI_COMPATIBLE_PRICE_PER_1M_INPUT/_OUTPUTを設定してください（そうしないと、上記の注記のとおり、このプロバイダーではコスト追跡/ガードレールは無効になります）。

完全にカスタムなプロバイダー（自己ホストモデル、まったく異なるAPI形状）を追加するには、src/providers/openaiCompatibleProvider.jsを出発点としてコピーし、以下を実装します：

async function ask(imageBuffer, mimeType, question) {
  // return { text: string, costUsd: number | null }
}
module.exports = { ask };

そして、src/providers/visionProvider.jsのloadProvider()に名前を付けて登録します。

ライセンス

MIT

Kinect.PROによって開発されました