Como Construímos um Servidor MCP em Tempo Real para Godot

Por que “Tempo Real” Importa para um Servidor MCP no Godot

A maioria das demonstrações de MCP funciona com um mundo em formato REST: o modelo faz uma pergunta, uma ferramenta retorna JSON, e ninguém se importa se a ida e volta levou dois segundos. Godot é diferente. O editor possui uma árvore de cenas viva, importações de recursos e um loop de modo de jogo. Se o seu servidor MCP bloqueia a thread principal—ou apenas vê um dump desatualizado do projeto—os clientes de IA deixam de parecer copilotos e começam a parecer editores de arquivos remotos com etapas extras.

Quando projetamos o Godot MCP para a VberAI, o briefing era explícito:

• Um assistente de IA (Cursor, Claude, Windsurf e clientes MCP similares) deve operar o editor, não apenas ler arquivos .gd do disco
• Ações como criar nó, renomear, anexar script e consultar seleção devem ser concluídas enquanto o editor permanece responsivo
• Os contextos de modo de jogo e modo de edição devem permanecer honestos—as ferramentas devem falhar alto quando uma operação é insegura durante o jogo

Este post é a história de engenharia: como construímos um servidor MCP em tempo real que fica ao lado do Godot em vez de fingir que o projeto é um repositório estático.

O Problema com MCP “Somente Arquivos” para Motores

Uma abordagem ingênua é tentadora:

1. Aponte o servidor MCP para a pasta do projeto
2. Exponha read_file / write_file / list_dir
3. Deixe o modelo inventar GDScript e esperar que o editor recarregue bem

Isso funciona para sites de documentação. Falha para trabalho de motor porque:

• A propriedade da cena vive na memória — diffs de .tscn não salvos, cenas abertas e seleção do editor são invisíveis no disco
• Os pipelines de importação são stateful — escrever um PNG não é o mesmo que “recurso pronto com configurações de importação corretas”
• Sinais e caminhos de nós são dados de grafo — edições de string quebram a fiação silenciosamente
• A latência se acumula — cada confirmação de “o nó apareceu?” se torna outra varredura completa do sistema de arquivos

Precisávamos de uma superfície MCP que espelhasse o que um humano já vê no dock do Godot: hierarquia, propriedades em formato de inspetor e identificadores de recursos—não apenas strings de caminho.

Visão Geral da Arquitetura

Em alto nível, o Godot MCP é três camadas cooperantes:

Cliente MCP (Cursor / Claude / …)
        │  JSON-RPC sobre stdio ou transporte local
        ▼
Servidor MCP (processo de ponte VberAI Godot)
        │  fila de comandos + envelopes de resultado
        ▼
Plugin do Editor Godot (GDExtension / plugin do editor)
        │  chamadas adiadas na thread principal
        ▼
Árvore de Cenas do Editor / ResourceDB / Editor de Script

Camada 1 — Superfície de ferramentas MCP

As ferramentas são intencionalmente pequenas e em formato de verbo:

• godot_get_scene_tree — instantâneo da cena editada com tipos de nós e caminhos
• godot_create_node / godot_set_property
• godot_attach_script / godot_run_script_snippet (protegido)
• godot_list_resources / godot_get_selection

Evitamos uma ferramenta gigante do_anything. Ferramentas menores são mais fáceis de validar, mais fáceis de registrar e mais difíceis de um modelo abusar em patches ilimitados.

Camada 2 — a ponte em tempo real

A ponte é onde o “tempo real” realmente vive:

• Um canal bidirecional entre o processo MCP e o plugin do editor (socket local ou pipe nomeado em desenvolvimento; builds de produto podem envolver isso no assistente de desktop VberAI)
• Uma fila de comandos que serializa mutações para que duas chamadas de ferramenta sobrepostas não possam competir com a árvore de cenas
• IDs de requisição + confirmações para que o cliente MCP possa esperar por “aplicado” sem consultar o sistema de arquivos
• Heartbeat / liveness do editor para que os clientes saibam quando o Godot saiu no meio da sessão

Camada 3 — Segurança da thread principal no Godot

As APIs de UI e cena do Godot não são de thread livre. O plugin nunca muta nós na thread de I/O do MCP. Em vez disso:

1. O comando MCP chega na thread da ponte
2. O payload é enfileirado
3. O callback adiado do editor roda na thread principal (call_deferred / hook de frame ocioso)
4. O envelope de resultado retorna sucesso, erro estruturado ou “tente novamente após o modo de jogo terminar”

Esse padrão é chato por design. Chato é o que mantém o “tempo real” de se tornar “congelamentos aleatórios do editor”.

Tornando-o Realmente em Tempo Real (Sem Mentir Sobre Latência)

“Tempo real” aqui não significa latência zero mágica. Significa o loop de feedback corresponde a como humanos trabalham no editor.

Instantâneo vs fluxo

Protótipos iniciais retornavam toda a árvore de cenas em cada chamada. Isso colapsava em configurações grandes de mundo aberto. Mudamos para:

• Instantâneos rasos por padrão (raiz + um nível, ou focado na seleção)
• Leituras com escopo de caminho quando o modelo já conhece uma subárvore
• Tokens de mudança opcionais para que chamadas subsequentes possam perguntar “o que mudou desde X?” em vez de re-serializar tudo

Resultados amigáveis a diffs

Os resultados das ferramentas incluem:

• Strings canônicas de NodePath
• Nomes de tipos (CharacterBody2D, Control, …)
• Chaves de propriedade que mapeiam limpo para campos do inspetor
• Avisos explícitos quando uma escrita foi aplicada, mas a cena ainda está suja / não salva

Os modelos iteram mais rápido quando os resultados parecem estado de UI, não como um post de blog de texto livre.

Comportamento limitado do modo de jogo

O modo de jogo é onde metade dos tickets de “IA quebrou meu projeto” começam. Nosso conjunto de regras:

Modo	Permitido	Bloqueado ou limitado
Edição	Mutações de cena, consultas de recursos	Exclusões destrutivas de projeto sem confirmação
Jogo	Principalmente leitura / consulta de nós em runtime	Edições estruturais na cena editada
Transição	Dicas de espera / tentar novamente	No-ops silenciosos

Erros claros vencem a esperteza. Se o modelo não pode editar durante o jogo, a resposta MCP diz isso em forma estruturada—para que o cliente possa dizer ao usuário para parar o jogo e tentar novamente.

Problemas Difíceis que Enfrentamos (e Mantivemos)

1. O editor não é um banco de dados

Ordem de nós, relacionamentos de dono e cenas empacotadas interagem de maneiras que parecem simples em um GIF e bagunçadas em um .tscn. Apoiamo-nos nas próprias APIs do Godot (Node, EditorInterface, carregadores de recursos) em vez de inventar um modelo de cena paralelo que se desviaria.

2. Scripts vs cenas como duas fontes de verdade

Anexar um script não é o mesmo que garantir que o script compila e o nome da classe resolve. O servidor relata resultados de compilação/anexação separadamente. Isso interrompeu uma classe de falhas de “ferramenta disse sucesso, Inspetor não mostra nada”.

3. Sessões multi-janela / multi-projeto

Desenvolvedores abrem mais de uma instância do Godot. A ponte se liga a um ID de sessão explícito do editor para que chamadas de ferramenta não caiam no projeto errado após um fim de semana de sono + reabrir.

4. Limites de segurança

Um servidor MCP que pode reescrever cenas é poderoso. Transporte local-first, allowlists explícitas de ferramentas e nenhuma exfiltração silenciosa em nuvem da árvore completa do projeto são inegociáveis. “Assistente de IA” e “shell remoto sobre seu jogo” devem permanecer categorias de produto distintas.

Como Isso se Encaixa ao Lado do AI Studio e do Resto da VberAI

O Godot MCP é o operador de motor. Peças complementares:

• VberAI Studio (AI Studio) — estrutura de design para motor de Figma/PSD → hierarquias de Control; o MCP então conecta botões e renomeia nós após a importação
• Unity MCP / Cocos MCP — mesma ideia de MCP, diferentes hosts de editor e regras de segurança
• AI Super Matting — limpa alfa antes que texturas se tornem recursos de motor que o MCP atribui depois

A tese compartilhada: a IA deve tocar a superfície de produção viva (editor, assets, cenas), não apenas o repositório como texto.

Dicas Práticas se Você Está Construindo Seu Próprio MCP de Motor

1. Enfileire mutações na thread principal do motor — nunca finja que motores de jogo são servidores sem compartilhamento
2. Prefira ferramentas pequenas com esquemas — validação vence poesia de prompt
3. Retorne NodePaths e tipos, não prosa — modelos precisam de identificadores operáveis
4. Codifique modos de jogo/edição em cada resposta — ambiguidade aqui destrói confiança
5. Meça a ida e volta até “visível no dock” — não apenas o tempo de codificação JSON

Se você apenas otimizar o processo MCP e ignorar a ponte do editor, você entregará um loop rápido de alucinação.

Conclusão

Construir um servidor MCP em tempo real para Godot significou tratar o editor como um colaborador vivo: uma ponte enfileirada e segura para a thread principal; ferramentas em formato de ações do editor; e honestidade sobre os limites do modo de jogo. MCP somente arquivos é mais fácil—e incompleto para trabalho nativo de cena.

Quer o caminho enviado em vez de um protótipo de fim de semana? Comece com VberAI Godot MCP, conecte seu cliente MCP preferido e tente uma primeira chamada de ferramenta trivial: liste a árvore de cenas atual e crie um nó sob a seleção. Esse único loop—consultar → mutar → vê-lo no dock—é o produto. Todo o resto é engenharia de confiabilidade em torno dele.