LLM による制御（MCP）

Wails v3 には、LLM エージェント（Claude Code、IDE アシスタント、任意の MCP クライアント）が実行中の Wails アプリケーションを検査、テスト、操作できる、組み込みのModel Context Protocol（MCP）サーバーがあります。

プロジェクトのライフサイクルを自動化するには、別のwails3 mcp CLI サーバーを使用してください。このサーバーにより、エージェントはプロジェクトの検査と初期化、診断の実行、ビルドおよび開発ジョブの開始、バインディングの生成、名前付き Taskfile タスクの実行、上限付きジョブ出力の取得を行えます。CLI サーバーはデフォルトで現在のディレクトリ内に制限され、任意のシェルコマンドを実行する機能は公開しません。トランスポート、認証、ツールの詳細については、CLI MCP ドキュメントを参照してください。

有効にすると、アプリに接続したエージェントは次の操作を実行できます。

• ウィンドウの一覧表示と制御 — サイズ、位置、フォーカス、フルスクリーン、開発者ツール、再読み込みなど
• DOM の検査 — 要素の検索、HTML の取得、構造スナップショットの取得
• JavaScript の評価 — 任意のウィンドウ内で任意のコードを実行し、結果を取得
• ユーザー入力のシミュレーション — マウスの移動、クリック、ドラッグ、スクロールをアニメーション付きの画面上のカーソルで表示し、エージェントの操作を確認可能
• 文字入力とキー操作 — React の制御コンポーネントによる入力でも動作する、実際に近い文字単位のイベント
• バインドされた Go メソッドの呼び出しと、アプリケーションイベントの発行および待機

仕組み

MCP サーバーがアプリケーションにコンパイルされるのは、mcp ビルドタグが指定されている場合だけです。このタグがなければ、サーバーコードはバイナリに一切含まれません。実行時のオーバーヘッドも、開いているポートも、攻撃対象領域もありません。

タグが指定されている場合、サーバーはApp.Run()内で自動的に起動し、デフォルトで127.0.0.1:9099にバインドして、そのエンドポイントをログに記録します。ユーザーコードは必要ありません。

チュートリアル

ステップ 1 — 通常の Wails アプリケーションを作成する

MCP では、インポートも登録も必要ありません。通常どおりアプリを作成してください。

package main

import (
    "embed"
    "log"

    "github.com/wailsapp/wails/v3/pkg/application"
)

//go:embed assets
var assets embed.FS

func main() {
    app := application.New(application.Options{
        Name: "My App",
        Assets: application.AssetOptions{
            Handler: application.BundledAssetFileServer(assets),
        },
    })

    app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title: "My App",
        Width: 1024, Height: 768,
    })

    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}

ステップ 2 — mcp タグを指定してビルドまたは実行する

# Development
WAILS_MCP=1 wails3 dev

# Production build
WAILS_MCP=1 wails3 build

go run -tags mcp .
go build -tags mcp -o myapp .

$env:WAILS_MCP = "1"
wails3 dev
# or
wails3 build

起動時に、アプリケーションは MCP エンドポイントをログに記録します。

INFO MCP server started. Connect MCP clients using the streamable HTTP transport.
     url=http://127.0.0.1:9099/mcp

ステップ 3 — クライアントを接続する

サーバーはMCP Streamable HTTP トランスポートを使用します。任意の MCP 互換クライアントで接続してください。

claude mcp add --transport http my-app http://127.0.0.1:9099/mcp

Click the "Submit" button, then verify a success toast appears.

{
  "github.copilot.chat.mcp.enabled": true,
  "mcp": {
    "servers": {
      "my-wails-app": {
        "type": "http",
        "url": "http://127.0.0.1:9099/mcp"
      }
    }
  }
}

http://127.0.0.1:9099/mcp

ステップ 4 — テストセッションを実行する

エージェントにアプリケーションの動作確認を依頼します。プロンプトの例を次に示します。

Take a DOM snapshot of the main window.

Click the "Add item" button, type "Hello world" in the input field,
then press Enter and verify the item appears in the list.

Call the bound method main.GreetService.Greet with argument ["World"]
and return the result.

Wait for the event "save:complete" while clicking the Save button.

設定

すべて環境変数で設定でき、コードを変更する必要はありません。

例 — カスタムポートと60秒のタイムアウト：

WAILS_MCP=1 WAILS_MCP_PORT=9200 WAILS_MCP_TIMEOUT=60000 wails3 dev

利用可能なツール

マルチウィンドウ対応

ウィンドウを操作するすべてのツールでは、ウィンドウの名前（WebviewWindowOptions.Nameで設定）を含む省略可能なwindow引数を指定できます。省略すると、現在フォーカスされているウィンドウが対象になります。フォーカスされているウィンドウがない場合は、最初のウィンドウが対象になります。

List all windows, then click the "New" button in the window named "editor".

要素の選択

マウスおよびキーボードツールでは、次のいずれかを指定できます。

• CSS セレクター — selector: "#submit-btn"（要素が自動的に表示領域内へスクロールされます）
• 座標 — x: 400, y: 300（ビューポートを基準とする CSS ピクセル）

ドラッグ操作では、from_およびto_を先頭に付けます。

Drag from selector: ".card" to selector: ".dropzone"

セキュリティ

• サーバーはデフォルトで127.0.0.1にバインドされます。ブラウザーのオリジンは HTTP(S) のループバックオリジンでなければなりません。不透明なオリジン（null）、不正な形式のオリジン、外部オリジンは拒否されます。
• ヘッダーを持たないネイティブ MCP クライアントも引き続きサポートされます。WAILS_MCP_TOKENを設定しない場合、ローカルプロセスおよび許可されたローカルブラウザーオリジンは信頼されます。オリジンチェックは認証ではありません。すべての/mcp呼び出しで Bearer 認証を必須にするには、十分なエントロピーを持つトークンを設定します。クライアントのAuthorization: Bearer <token>ヘッダーにも同じトークンを設定してください。プリフライトリクエストにはトークンは不要です。
• /eval-resultコールバックでは、クライアントの Bearer トークンではなく、評価ごとに予測不能な ID を使用するため、WebView の結果配信との互換性が維持されます。
• 本番ビルドにはmcpタグを含めるべきではありません。Wails CLI がこのタグを追加するのは、WAILS_MCP=1が明示的に設定されている場合のみです。また、デフォルトのwails3 buildにはサーバーコードが一切含まれていません。
• ループバック以外のインターフェイスでサーバーを公開する必要がある場合（LAN テストなど）は、WAILS_MCP_HOST=0.0.0.0と、十分なエントロピーを持つWAILS_MCP_TOKENを設定してください。トークンがない場合、起動に失敗します。組み込みリスナーは HTTP を使用するため、信頼できないネットワークでは暗号化トンネルまたは TLS 終端プロキシを使用してください。

サンプルアプリケーション

すべてのツールのデモを行う完全なプレイグラウンドアプリケーションをv3/examples/mcpで利用できます。次の機能が含まれています。

• インクリメント／リセットボタン付きカウンター
• Greet、Add、Shout の各バインドメソッドを備えた名前入力欄
• HTML5 ドラッグ＆ドロップのドラッグ元とドロップ先
• スクロール可能なリスト（50項目）
• イベントログ

次のコマンドで実行します。

cd v3/examples/mcp
go run -tags mcp .

次に、Claude Code または任意の MCP クライアントをhttp://127.0.0.1:9099/mcpに接続し、UI を操作するよう指示します。

フィードバック

組み込み MCP サーバーは実験的な機能であり、今後の方向性は皆さまからのフィードバックによって決まります。お試しになった場合は、使用したクライアントとツール、期待していた動作と実際に起きたこと、エージェントにアプリを操作させることが有用だったかどうかをぜひお聞かせください。実行した内容を正確に記載した報告が最も役立ちます。MCP サーバーのフィードバックディスカッションでお知らせください。