MCPサーバー操作編 | Gua 日本語リファレンス

先にゲームを起動する

AI clientstdio →gui-mcpWebSocket →Game bridge→Gua adapter

MCPサーバー自身はUI状態を持ちません。Godotアプリがブリッジを起動し、ws://127.0.0.1:8765で待ち受けている必要があります。

MCPクライアントへ登録

Bun環境では公開パッケージをbunxで起動する。クライアントの設定形式に合わせ、次のコマンドと引数を登録する。

MCP設定例json

{
  "mcpServers": {
    "gua": {
      "command": "bunx",
      "args": ["gui-mcp@latest", "mcp"],
      "env": {
        "GUA_BRIDGE_URL": "ws://127.0.0.1:8765",
        "GUA_ARTIFACT_DIR": ".gua"
      }
    }
  }
}

Semantic UIの取得と操作

get_ui_tree / wait_for_node

現在のtreeを取得し、ノードの出現や状態変化を待つ。

click_node / focus_node

安定IDのControlをクリックまたはfocusする。

set_value / set_checked / select

入力値、checkbox、選択Controlを意味情報で操作する。

scroll / press_key

Semantic対象へscrollまたはkey入力を送る。

get_screenshot / get_logs

公開済みPNGとランタイムログを取得する。

run_test

小さなwait/clickシーケンスを実行する。

ゲーム世界を観測

get_world_object_tree、find_world_objects、wait_for_world_objectは、明示的にopt-inされたWorld Object Treeを読み取ります。World v1は観測専用です。操作にはSemantic UIまたは範囲を限定したgame actionを使います。

ゲーム入力を操作

gui-mcpはSemantic Game Actionとraw keyboard、pointer、gamepad、textの固定tool群を一覧へ表示します。対応capabilityが有効でない操作はhostが呼び出し時に拒否します。stateful holdはowner単位・lease制限付きで、release_all_game_inputsまたは自動cleanupにより解放されます。requiresConfirmation付きactionには明示的な確認引数が必要です。

RecordingとReplay

start_recording / stop_recording

MCP経由のSemantic UI操作とgame-input操作を記録し、schema v2 documentを返す。

save_recording / replay_recording

artifact rootへ保存し、inline・保存名・直前のRecordingから再生する。

機密なUI／game-input stepは平文ではなくsecretKeyだけを記録します。Replay時の秘密値はmemory上のsecrets mapから解決し、最終cleanupではReplay ownerが保持する全game inputを解放します。座標fallbackは既定で拒否されます。

Visual比較

compare_screenshot

最新PNGを明示的なtest名・OS/renderer variantのbaselineと比較する。baseline更新は明示指定が必要。

get_visual_artifacts

actual、expected、diff、comparison manifestのパスを返す。

AIへの頼み方

プロンプト例text

GuaのUIツリーを取得し、「Start Game」ボタンを探してください。
見つかった安定IDを使ってクリックし、
「Loading...」が表示されるまで待ってください。
失敗した場合はログを確認し、UIツリーと原因を報告してください。

追加の観測値を読む

ゲームがobserve_v1を公開すると、gui-mcpはget_observe_snapshot、subscribe_observations、poll_observations、unsubscribe_observationsを提供します。値はゲーム側が登録し、clientからgetterをremote登録したりprofileを昇格したりできません。再接続やgapでは新しい購読が必要です。登録と購読を参照してください。

認可した物理providerをqueryする

native hostがTesting／Debug用spatial providerを明示的に有効化した場合にget_spatial_info／query_spatial_batchを使います。上限付きの物理queryで、Worldの半径検索とは別です。resetやscene／provider変更で無効になります。provider設定とqueryの制限を参照してください。

actionの値metadataを取得する

semantic_game_input_metadata_v1がある場合にget_game_input_actions_v2／find_game_input_actions_v2を明示的に使います。valueSchema／examplesは値の説明で、許可や確認の省略にはなりません。入力metadataの説明を参照してください。