LLM 控制（MCP）

Wails v3 內建模型上下文協定（MCP）伺服器，讓 LLM 代理（例如 Claude Code、IDE 助理或任何 MCP 用戶端）能檢查、測試及操控執行中的 Wails 應用程式。

若要自動化專案生命週期，請使用獨立的wails3 mcp CLI 伺服器。它可讓代理檢查及初始化專案、執行診斷、啟動建置與開發工作、產生繫結、執行具名的 Taskfile 工作，以及擷取有界限的工作輸出。CLI 伺服器預設僅限存取目前目錄，且不會開放任意 Shell 指令執行功能。如需傳輸、驗證及工具的詳細資訊，請參閱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 可串流 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

可用工具

多視窗支援

所有會對視窗執行操作的工具都接受選用的window引數，其中包含視窗的名稱（透過WebviewWindowOptions.Name設定）。若省略此引數，工具會以目前取得焦點的視窗為目標；若沒有視窗取得焦點，則以第一個視窗為目標。

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呼叫都必須使用持有人驗證，並在用戶端的Authorization: Bearer <token>標頭中設定相同權杖。預檢要求不需要此權杖。
• /eval-result回呼使用每次求值時都無法預測的 ID，而非用戶端持有人權杖，因此仍與 WebView 結果傳遞相容。
• 正式環境組建不應包含mcp標籤。Wails CLI 只會在明確設定WAILS_MCP=1時加入此標籤，而預設的wails3 build完全不含伺服器程式碼。
• 若需要在非回送介面上公開伺服器（例如進行區域網路測試），請設定WAILS_MCP_HOST=0.0.0.0及高熵WAILS_MCP_TOKEN；若未設定權杖，啟動將會失敗。由於內建接聽程式使用 HTTP，請在不受信任的網路上使用加密通道或終止 TLS 的 Proxy。

範例應用程式

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 伺服器意見回饋討論告訴我們。