Ilusion: Plataforma Desktop com MCP Server Embutido

Como arquitetei uma plataforma desktop em Go + Wails v3 com DDD, CQRS, Mediator, Google Calendar sync bidirecional e um servidor MCP que expõe domínios para LLMs.

Por Emanuel Nunes

Publicado em: 25 de abril de 2026 às 00:00

O que é o Ilusion

O Ilusion é uma aplicação desktop escrita em Go com Wails v3 que gerencia projetos, tarefas e agenda. Ele funciona como o corpo operacional da Melissa — quando conectada via MCP, a Melissa ganha acesso a todos os domínios da plataforma.

Roda como binário nativo no Windows usando WebView2 para a UI. O frontend é Vite + TypeScript embutido via embed.FS.

Arquitetura

O código segue uma separação em 4 camadas:

internal/
├── domain/          # Entidades e eventos de domínio puros
├── application/     # Commands, Queries e Mediator (CQRS)
├── infrastructure/  # Persistência, busca, Google Calendar, backup
├── interface/       # Bindings Wails (ponte Go ↔ frontend)
└── mcp/             # Servidor MCP (JSON-RPC 2.0 via Stdio)

Domain Layer

Bounded Contexts implementados:

Domínio	O que faz
`domain/project`	Projetos com status (active, paused, completed, archived), prioridade e metadata
`domain/task`	Tarefas hierárquicas (subtasks via `parent_id`), com status machine (open → in_progress → blocked → completed → cancelled)
`domain/agenda`	Eventos de calendário com recorrência (RRULE-like), reminders, attendees, Google Meet, RSVP e color coding
`domain/event`	Event Bus — cada mutação emite um evento de domínio tipado
`domain/vo`	Value Objects compartilhados
`domain/ports`	Interfaces de repositório (Ports & Adapters)

Application Layer — CQRS + Mediator

A camada de aplicação implementa CQRS com um Mediator central:

Commands: CreateProject, UpdateProject, ArchiveProject, CreateTask, UpdateTask, MoveTask, DeleteTask, CreateCalendarEvent, UpdateCalendarEvent, RescheduleEvent, DeleteCalendarEvent, RSVPEvent
Queries: ListProjects, GetProject, ListTasks, ListCalendarEvents, FreeBusy, Search
Mediator: Concentra todos os handlers. Recebe DTOs tipados, despacha para o handler correto e retorna resultado.

O Mediator é injetado tanto nos Bindings Wails (UI) quanto no MCP Server (LLM), garantindo que ambos usem a mesma lógica de aplicação.

Infrastructure Layer

Pacote	Responsabilidade
`persistence`	SQLite via modernc.org/sqlite. Migrations, repositories e Event Store
`search`	FTS5 (Full-Text Search) sobre todas as entidades
`google`	Sync bidirecional com Google Calendar (multi-account, OAuth2)
`eventbus`	Event Bus in-memory com subscribers
`backup`	Backup automático do SQLite na inicialização
`export`	Exportação de dados
`melissapoller`	Poller que consome telemetria da Melissa (eventos de uso) via HTTP
`desktop`	Hotkey global (Alt+A) para toggle do overlay da Melissa

Google Calendar Sync

O sync com Google Calendar é bidirecional e multi-account:

Contas configuradas: Pessoal (OAuth2 Desktop Flow) e Wicomm (OAuth2 separado). Cada conta tem seu token, calendar ID e sync state.
Sync interval: A cada 30 segundos. Além disso, qualquer mutação local (criação, update, reschedule, delete) dispara um ForceSync imediato via Event Bus.
Idempotência: Cada evento sincronizado é rastreado no DB via google_sync_state.
Funcionalidades: Eventos recorrentes, reminders, attendees, Google Meet, RSVP (aceitar/recusar/tentativo) e color IDs.

Servidor MCP

O Ilusion embute um servidor Model Context Protocol (JSON-RPC 2.0 via Stdio) que roda de duas formas:

Headless (ilusion.exe mcp): Roda apenas o servidor MCP sem UI. Stdout é blindado para o JSON-RPC; logs vão para stderr.
Embutido: Roda em background junto com a aplicação Wails.

O servidor expõe Tools, Resources e Prompts:

Tools (16 tools registradas)

Projetos: create_project, list_projects, get_project, update_project, archive_project

Tarefas: create_task, list_tasks, update_task, move_task, delete_task

Agenda: create_event, list_events, update_event, reschedule_event, delete_event, get_freebusy, rsvp_event

Busca: search — busca unificada via FTS5 sobre projetos, tarefas, notas e eventos

As tools incluem fallbacks para alucinações comuns de LLMs (por exemplo, aceitar tanto start quanto start_time nos parâmetros de eventos).

Conexão com a Melissa

A Melissa se conecta ao Ilusion via MCP Client (Stdio). O Ilusion aparece como um servidor MCP no .mcp.json da Melissa. Quando conectada, a Melissa pode:

Consultar a agenda da semana
Criar e reagendar eventos no Google Calendar
Gerenciar projetos e tarefas
Buscar semanticamente qualquer entidade

Além disso, o Ilusion roda um poller de telemetria que consome eventos de uso da Melissa (tokens, latência, custos) e persiste no SQLite local, com idempotência via UNIQUE(agent_start_id, seq).

Overlay da Melissa

O Ilusion tem uma integração visual com a Melissa. O Agente é iniciado como processo filho (AgentBinding) com lifecycle management completo. Um hotkey global Alt+A (registrado via Win32 API) faz toggle de uma janela overlay transparente para interação rápida com a Melissa sem sair do contexto de trabalho.

Stack

Camada	Tecnologia
Linguagem	Go 1.25
Desktop Runtime	Wails v3 (alpha.74)
UI	Vite + TypeScript (embebido via embed.FS)
DB	SQLite (modernc.org/sqlite)
Busca	FTS5
Calendar	Google Calendar API v3 (multi-account OAuth2)
Padrão arquitetural	DDD + CQRS + Mediator + Event Sourcing
Integração IA	MCP Server (JSON-RPC 2.0, Stdio)
Process Management	AgentBinding (processo filho com hotkey global)