expo-headless-mcp

expo-headless-mcp

AI が エミュレーター、スマートフォン、ブラウザーを使わずに Expo／React Native アプリを確認して操作できる MCP サーバーです。PNG の実スクリーンショット、タップ、文字入力、スクロール、自動バグ検出に対応しています。（ロシア語版：README.ru.md）

ドキュメント

• 使い始める — Claude Code／Claude Desktop／Cursor へのインストール、初回実行
• ツールのリファレンス — すべてのツールとパラメーター
• デバイスモード — Android エミュレーター／スマートフォンと iOS Simulator、同意と安全性の仕組み
• 仕組み — アーキテクチャ、サポート内容、開発
• トラブルシューティング

仕組み

Metro と Expo Go にはネイティブランタイムが必要なため、代わりに次のように動作します。

1. esbuild がプロジェクト（App.* または main）をバンドルし、react-native を軽量なシム（src/shim/rn.js）に、ネイティブ専用パッケージ（expo-*、react-native-*）をスタブに置き換えます。
2. アプリは Node で動作し、React は独自のツリー（react-reconciler）にレンダリングします。
3. レイアウトは Yoga（React Native が使用するフレックスボックスエンジン）で計算され、Skia（@napi-rs/canvas）で PNG に描画されます。

制限事項：実際の iOS／Android ではなく、近似的な表示です。フォント、影、アニメーション、ネイティブモジュールには違いがあります。expo-router／react-navigation はサポートされていません。refresh_screen で状態がリセットされます。

ツール

• refresh_screen — 画面を再構築して表示します（projectPath、entry、width、height、scale、reload）
• click_screen — x,y または target（testID／テキスト）、long、alert:<button> を指定してタップします
• type_text — TextInput に入力します（target または x,y、submit、append）
• scroll_screen — x,y の位置の下にある領域をスクロールします
• describe_screen — 要素のテキスト概要とレイアウト警告（重なり、テキストの切り取り、画面外への表示）を表示します
• auto_test — すべてを自動テストします。再読み込みを複数回行い、すべての入力欄にさまざまなデータ（空、不正、有効、非常に長い文字列、特殊文字、キリル文字、CJK、アラビア語／ヘブライ語、絵文字）を入力し、すべてのボタン／スイッチをタップし（必要に応じてスクロールして到達）、アラートを閉じます。クラッシュ、コンソールエラー、レイアウトの問題、動作しないボタンをスクリーンショットとともに報告します。

サーバーには組み込みの instructions があり、コードを変更した後、AI は再ビルドして手動で確認し、auto_test を実行し、問題を修正して、すべてのテストに問題なく合格するまで繰り返す必要があります。MCP プロンプト verify_changes を実行すると、同じループが開始されます。

言語

サーバーのテキストは英語で、AI はユーザーが使用する言語で応答します。レンダリングでは、ラテン文字、キリル文字、CJK、デーヴァナーガリー文字、アラビア文字、ヘブライ文字、絵文字にシステムフォントが使用されます（Linux では Noto フォントをインストールしてください）。右から左への レイアウト（I18nManager）はシミュレートされませんが、RTL テキスト自体は表示されます。

インストール

claude mcp add expo -e EXPO_PROJECT=/path/to/app -- npx -y expo-headless-mcp

テスト：npm test（エンドツーエンド）、node test/mcp.js（stdio）。

実機モード（任意）

ヘッドレスレンダラーに加えて、AI は adb（Windows、macOS、Linux）を通じてAndroid エミュレーターまたは USB 接続のスマートフォン上の Expo Goを操作でき、起動済みの iOS Simulator（macOS と Xcode が必要）も操作できます。物理 iPhone はサポートされていません。Apple は大がかりなツールなしでのリモート入力を許可していないため、iPhone ではご自身で Expo Go を開いてください。

ツール：device_list（読み取り専用）、use_target（device / headless）、press_key、デバイスを操作する refresh_screen、click_screen、type_text、scroll_screen、describe_screen。

サーバーに組み込まれた安全ルール：

• 何も接続されていない／adb が見つからない場合 → その旨を伝え、何も変更せず、アプリをご自身で確認する（またはヘッドレスモードを使用する）よう勧めます。
• USB デバッグがオフまたは未承認の場合 → 有効にする方法を説明し、スマートフォンをタップ、入力、スクロールして操作することを事前に警告します。
• 最初に同意を確認します。 物理スマートフォンを操作する前、Expo Go が見つからない場合にインストールする前、プロジェクトと SDK が一致しない Expo Go を置き換える前（対応するビルドは Expo の公式リリース一覧から取得します。ダウングレードには先にアンインストールが必要であることを質問で伝えます）に、確認を求めます（MCP のエリシテーション、またはクライアントにその機能がない場合はチャット内の AI を通じて確認します）。同意しない場合は何も実行せず、再度確認することもありません。
• Expo Go のみを操作します。タップ、入力、スワイプの前に、毎回 Expo Go がフォアグラウンドにあることを確認します。使用できるキー：back、enter、tab、delete。
• auto_test はヘッドレスモード専用です（すべてをタップします）。adb では ASCII 以外のテキストを入力できないため、他の言語はヘッドレスモードでテストしてください。

ステータス： Android の操作経路は作者が実機で使用しており、偽の adb を使った自動テストでカバーされています。

開発サーバーを起動すると、プロジェクト内で npx expo start が実行されます（依存関係が不足している場合は、npm install の実行前に確認を求めます）。EXPO_MCP_METRO_CMD でコマンドを上書きできます。特定の adb を使うには EXPO_MCP_ADB を設定してください。

iOS Simulator に関する注意

• macOS + Xcode（xcrun simctl）と、タップ／入力／UI ツリー表示用の Facebook idb が必要です（brew tap facebook/fb && brew install idb-companion && pip3 install fb-idb）。idb がない場合、サーバーはインストール方法を案内するだけで、インストールすることはありません。
• プロジェクトの SDK に対応する Expo Go は、同意を得てからのみインストールまたは置き換えられます（Expo のリリース一覧から取得した公式ビルドを使用します）。
• シミュレーターは使い捨てのため、アプリごとのフォーカス確認はありません。iOS にはハードウェアの戻るキーもありません。
• ステータス： iOS の操作経路は、偽の xcrun／idb を使ったテストでのみカバーされています。実際の Mac ではまだ実行されていません。