先にゲームを起動する
AI clientstdio →gui-mcpWebSocket →Game bridge→Gua adapter
MCPサーバー自身はUI状態を持ちません。Godotアプリがブリッジを起動し、ws://127.0.0.1:8765で待ち受けている必要があります。
MCPクライアントへ登録
Bun環境では公開パッケージをbunxで起動する。クライアントの設定形式に合わせ、次のコマンドと引数を登録する。
{
"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シーケンスを実行する。
RecordingとReplay
start_recording / stop_recording
MCP経由のSemantic actionを記録し、schema v1 documentを返す。
save_recording / replay_recording
artifact rootへ保存し、inline・保存名・直前のRecordingから再生する。
機密なset_valueは平文ではなくsecretKeyだけを記録します。Replay時の秘密値はmemory上のsecrets mapから解決されます。座標fallbackは既定で拒否されます。
Visual比較
compare_screenshot
最新PNGを明示的なtest名・OS/renderer variantのbaselineと比較する。baseline更新は明示指定が必要。
get_visual_artifacts
actual、expected、diff、comparison manifestのパスを返す。
AIへの頼み方
GuaのUIツリーを取得し、「Start Game」ボタンを探してください。
見つかった安定IDを使ってクリックし、
「Loading...」が表示されるまで待ってください。
失敗した場合はログを確認し、UIツリーと原因を報告してください。