LLM 제어(MCP)

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에는 import나 등록이 필요하지 않습니다. 평소와 같은 방식으로 앱을 만드세요.

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

사용 가능한 도구

다중 창 지원

창에 작용하는 모든 도구는 창의 이름(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 서버 피드백 토론에서 의견을 들려주세요.