Поиск
Внести изменения

Редактировать эту документацию

Переведите документацию или откройте весь проект на своём компьютере.

Ничего не будет опубликовано, пока вы не решите отправить свою работу.

Управление с помощью LLM (MCP)

Позвольте LLM-агентам тестировать ваше приложение и управлять им через Model Context Protocol

В Wails v3 встроен сервер Model Context Protocol (MCP), который позволяет LLM-агентам — Claude Code, помощникам в IDE или любым MCP-клиентам — исследовать, тестировать и контролировать работающее приложение Wails.

Для автоматизации жизненного цикла проекта используйте отдельный wails3 mcp CLI-сервер. Он позволяет агентам исследовать и инициализировать проекты, запускать диагностику, сборки и задачи разработки, создавать привязки, запускать именованные задачи Taskfile и получать ограниченный объём выходных данных задач. По умолчанию CLI-сервер работает только в текущем каталоге и не предоставляет возможности выполнять произвольные команды оболочки. Сведения о транспорте, аутентификации и инструментах см. в документации по CLI MCP.

После включения подключённый к приложению агент может:

  • Получать список окон и управлять ими — изменять размер и положение, переводить фокус, включать полноэкранный режим, открывать инструменты разработчика, перезагружать и т. д.
  • Исследовать DOM — находить элементы, получать HTML и создавать структурный снимок
  • Выполнять JavaScript — запускать произвольный код в любом окне и получать результат
  • Имитировать пользовательский ввод — перемещения мыши, щелчки, перетаскивания и прокрутку, отображаемые с помощью анимированного экранного указателя, чтобы вы могли наблюдать за работой агента
  • Вводить текст и нажимать клавиши — реалистичные события для каждого символа, совместимые с управляемыми полями ввода React
  • Вызывать привязанные методы Go, а также генерировать и ожидать события приложения

Как это работает

MCP-сервер компилируется в приложение, только если указан тег сборки mcp. Без этого тега код сервера полностью отсутствует в исполняемом файле: нет накладных расходов во время выполнения, открытых портов и поверхности атаки.

Если тег указан, сервер автоматически запускается внутри App.Run(), по умолчанию привязывается к 127.0.0.1:9099 и записывает свою конечную точку в журнал. Пользовательский код не требуется.

Учебное руководство

Шаг 1 — напишите обычное приложение Wails

Для MCP не нужны ни импорты, ни регистрация. Создайте приложение обычным способом:

main.go
go
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

Задайте WAILS_MCP=1, и Wails CLI автоматически добавит тег mcp:

shell
# Development
WAILS_MCP=1 wails3 dev

# Production build
WAILS_MCP=1 wails3 build

При запуске приложение записывает конечную точку MCP в журнал:

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

Шаг 3 — подключите клиент

Сервер использует потоковый HTTP-транспорт MCP. Подключитесь с помощью любого MCP-совместимого клиента.

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

Затем попросите Claude взаимодействовать с приложением:

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

Шаг 4 — проведите тестовый сеанс

Попросите агента проверить приложение в работе. Ниже приведено несколько примеров запросов:

text
Take a DOM snapshot of the main window.
text
Click the "Add item" button, type "Hello world" in the input field,
then press Enter and verify the item appears in the list.
text
Call the bound method main.GreetService.Greet with argument ["World"]
and return the result.
text
Wait for the event "save:complete" while clicking the Save button.

Конфигурация

Вся конфигурация задаётся с помощью переменных среды — изменять код не требуется.

Переменная среды Значение по умолчанию Описание
WAILS_MCP (не задано) Установите значение 1, true, on или yes, чтобы при использовании Wails CLI автоматически добавлялся тег сборки mcp.
WAILS_MCP_HOST 127.0.0.1 Интерфейс для привязки. Для привязки не к интерфейсу обратной петли требуется WAILS_MCP_TOKEN.
WAILS_MCP_TOKEN не задано Необязательный токен предъявителя при использовании интерфейса обратной петли; обязателен для других адресов привязки. Клиенты отправляют Authorization: Bearer <token>.
WAILS_MCP_PORT 9099 Порт для приёма подключений. Установите значение 0, чтобы использовать случайно назначенный свободный порт (он будет указан в журнале).
WAILS_MCP_TIMEOUT 30000 Тайм-аут выполнения JavaScript по умолчанию в миллисекундах.
WAILS_MCP_HIDE_CURSOR (не задано) Установите значение 1 или true, чтобы отключить наложение анимированного указателя.

Пример: пользовательский порт и тайм-аут 60 секунд:

shell
WAILS_MCP=1 WAILS_MCP_PORT=9200 WAILS_MCP_TIMEOUT=60000 wails3 dev

Доступные инструменты

Инструмент Назначение
app_info Сведения о приложении: платформа, архитектура, все окна и конечная точка MCP
windows_list Список всех окон с их геометрией и состоянием
window_control Перевести фокус, изменить размер, переместить, включить полноэкранный режим, открыть инструменты разработчика, перезагрузить, задать URL и т. д. (действий: 22)
js_eval Выполнить JavaScript в окне (асинхронное тело, return для значения)
dom_html Получить HTML-код страницы или определённого элемента
dom_query Найти элементы по CSS-селектору — тег, текст, границы, видимость
screenshot_dom Структурный снимок видимой страницы (на основе DOM, без пикселей)
mouse_move Анимированно переместить курсор в указанную точку или к элементу по CSS-селектору
mouse_click Выполнить щелчок анимированным курсором (левой, правой или средней кнопкой, двойной щелчок, клавиши-модификаторы)
mouse_drag Перетащить объект анимированным курсором (поддерживаются HTML5-элементы с функцией перетаскивания)
mouse_scroll Прокрутить содержимое в указанной точке или элементе
keyboard_type Посимвольно ввести текст с реалистичными событиями
keyboard_press Нажать одну клавишу (Enter, Tab, Escape, ArrowDown, …), при необходимости с клавишами-модификаторами
call_bound_method Вызвать метод привязанного сервиса Go, например main.GreetService.Greet
emit_event Отправить событие приложения Wails
wait_for_event Дождаться события приложения Wails и вернуть его данные

Поддержка нескольких окон

Все инструменты, работающие с окном, принимают необязательный аргумент window, содержащий имя окна (задаётся через WebviewWindowOptions.Name). Если аргумент не указан, инструмент работает с окном, находящимся в фокусе, а если такого окна нет — с первым окном.

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

Выбор элементов

Инструменты для работы с мышью и клавиатурой принимают один из следующих вариантов:

  • CSS-селектор — selector: "#submit-btn" (элемент автоматически прокручивается в область видимости)
  • Координаты — x: 400, y: 300 (в CSS-пикселях относительно области просмотра)

Для операций перетаскивания используйте префиксы from_ и to_:

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

Безопасность

  • По умолчанию сервер привязывается к 127.0.0.1. Источниками браузера могут быть только loopback-источники HTTP(S); непрозрачные (null), некорректные и внешние источники отклоняются.
  • Нативные клиенты MCP без заголовков по-прежнему поддерживаются. Без WAILS_MCP_TOKEN локальные процессы и разрешённые локальные источники браузера считаются доверенными; проверка источника не является аутентификацией. Задайте токен с высокой энтропией, чтобы требовать аутентификацию по схеме Bearer для всех вызовов /mcp. Укажите тот же токен в заголовке Authorization: Bearer <token> клиента. Для предварительных запросов токен не требуется.
  • Обратный вызов /eval-result использует непредсказуемые идентификаторы для каждого вычисления, а не Bearer-токен клиента, поэтому доставка результатов из webview остаётся совместимой.
  • Сборки для промышленной эксплуатации не должны включать тег mcp. Wails CLI добавляет его только при явном указании WAILS_MCP=1, а стандартная сборка wails3 build не содержит кода сервера.
  • Если сервер необходимо сделать доступным через интерфейс, не являющийся loopback-интерфейсом (например, для тестирования по локальной сети), задайте WAILS_MCP_HOST=0.0.0.0 и WAILS_MCP_TOKEN с высокой энтропией; без токена запуск завершится ошибкой. В недоверенных сетях используйте зашифрованный туннель или прокси-сервер с завершением TLS, поскольку встроенный слушатель использует HTTP.

Пример приложения

Полное приложение-песочница, демонстрирующее все инструменты, доступно по адресу v3/examples/mcp. Оно включает:

  • Счётчик с кнопками увеличения и сброса
  • Поле для ввода имени с привязанными методами Greet, Add и Shout
  • Источник и цель для перетаскивания HTML5
  • Прокручиваемый список (50 элементов)
  • Журнал событий

Запустите его следующей командой:

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

Затем подключите Claude Code или любой клиент MCP к http://127.0.0.1:9099/mcp и попросите его протестировать пользовательский интерфейс.

Обратная связь

Встроенный сервер MCP — экспериментальная функция, и от ваших отзывов зависит её дальнейшее развитие. Если вы её опробуете, нам будет интересно узнать, какие клиент и инструменты вы использовали, чего ожидали и что произошло на самом деле, а также было ли полезно позволить агенту управлять вашим приложением. Самые полезные отчёты точно указывают, что именно запускалось. Расскажите нам об этом в обсуждении отзывов о MCP Server.

Редактировать страницу

Последнее обновление: