Come Abbiamo Costruito un Server MCP in Tempo Reale per Godot

Perché il “Tempo Reale” è Importante per un Server MCP in Godot

La maggior parte delle demo MCP funziona in un mondo stile REST: il modello fa una domanda, uno strumento restituisce JSON, e a nessuno importa se il round trip ha richiesto due secondi. Godot è diverso. L’editor possiede un scene tree vivo, import di risorse, e un loop di play-mode. Se il tuo server MCP blocca il thread principale—o vede solo una copia statica del progetto—i client AI smettono di sentirsi co-piloti e iniziano a sentirsi editor di file remoti con passaggi extra.

Quando abbiamo progettato Godot MCP per VberAI, il brief era esplicito:

• Un assistente AI (Cursor, Claude, Windsurf e simili client MCP) deve operare l’editor, non solo leggere file .gd dal disco
• Azioni come crea nodo, rinomina, allega script e query di selezione devono completarsi mentre l’editor rimane reattivo
• I contesti play-mode e edit-mode devono rimanere onesti—gli strumenti devono fallire rumorosamente quando un’operazione non è sicura durante il play

Questo post è la storia ingegneristica: come abbiamo costruito un server MCP in tempo reale che sta accanto a Godot invece di fingere che il progetto sia un repository statico.

Il Problema con l‘“Solo File” MCP per Motori

Un approccio ingenuo è allettante:

1. Punta il server MCP alla cartella del progetto
2. Esponi read_file / write_file / list_dir
3. Lascia che il modello inventi GDScript e spera che l’editor si ricarichi bene

Funziona per siti di documentazione. Fallisce per lavoro su motori perché:

• La proprietà della scena vive in memoria — diff .tscn non salvati, scene aperte e selezione dell’editor sono invisibili su disco
• Le pipeline di importazione sono stateful — scrivere un PNG non è la stessa cosa di “risorsa pronta con impostazioni di import corrette”
• Segnali e percorsi nodo sono dati grafici — modifiche alle stringhe rompono il cablaggio silenziosamente
• La latenza si accumula — ogni conferma “il nodo è apparso?” diventa un’altra scansione completa del filesystem

Avevamo bisogno di una superficie MCP che rispecchiasse ciò che un umano vede già nel dock di Godot: gerarchia, proprietà in stile ispettore e handle di risorse—non solo stringhe di percorso.

Panoramica dell’Architettura

Ad alto livello, Godot MCP è composto da tre livelli cooperanti:

MCP Client (Cursor / Claude / …)
        │  JSON-RPC su stdio o trasporto locale
        ▼
MCP Server (processo bridge VberAI Godot)
        │  coda comandi + buste risultato
        ▼
Plugin Editor Godot (GDExtension / plugin editor)
        │  chiamate differite sul thread principale
        ▼
Scene Tree Editor / ResourceDB / Script Editor

Livello 1 — Superficie strumenti MCP

Gli strumenti sono intenzionalmente piccoli e a forma di verbo:

• godot_get_scene_tree — snapshot della scena modificata con tipi di nodo e percorsi
• godot_create_node / godot_set_property
• godot_attach_script / godot_run_script_snippet (protetto)
• godot_list_resources / godot_get_selection

Evitiamo un gigantesco strumento do_anything. Strumenti più piccoli sono più facili da validare, più facili da registrare e più difficili da abusare per un modello in patch illimitate.

Livello 2 — il bridge in tempo reale

Il bridge è dove vive realmente il “tempo reale”:

• Un canale bidirezionale tra il processo MCP e il plugin editor (socket locale o named pipe in sviluppo; le build di prodotto possono avvolgerlo dietro l’helper desktop VberAI)
• Una coda comandi che serializza le mutazioni così che due chiamate strumento sovrapposte non possano correre sul scene tree
• ID richiesta + acknowledgement così che il client MCP possa attendere “applicato” senza fare polling sul filesystem
• Heartbeat / liveness dell’editor così che i client sappiano quando Godot è uscito a metà sessione

Livello 3 — Sicurezza del thread principale in Godot

Le API UI e scene di Godot non sono free-threaded. Il plugin non muta mai i nodi sul thread I/O MCP. Invece:

1. Il comando MCP arriva sul thread del bridge
2. Il payload viene accodato
3. Il callback differito dell’editor viene eseguito sul thread principale (call_deferred / hook del frame idle)
4. La busta risultato restituisce successo, errore strutturato o “riprova dopo la fine del play mode”

Questo schema è noioso di proposito. La noia è ciò che impedisce al “tempo reale” di diventare “freeze casuali dell’editor”.

Renderlo Vivamente Reale (Senza Mentire sulla Latenza)

“Tempo reale” qui non significa latenza zero magica. Significa che il ciclo di feedback corrisponde a come gli umani lavorano nell’editor.

Snapshot vs stream

I primi prototipi restituivano l’intero scene tree a ogni chiamata. Crollava su grandi configurazioni open-world. Siamo passati a:

• Snapshot superficiali di default (root + un livello, o focalizzati sulla selezione)
• Letture con ambito percorso quando il modello conosce già un sottoalbero
• Token di modifica opzionali così che le chiamate successive possano chiedere “cosa è cambiato da X?” invece di riserializzare tutto

Risultati diff-friendly

I risultati degli strumenti includono:

• Stringhe NodePath canoniche
• Nomi di tipo (CharacterBody2D, Control, …)
• Chiavi di proprietà che mappano pulito ai campi dell’ispettore
• Avvisi espliciti quando una scrittura è stata applicata ma la scena è ancora sporca / non salvata

I modelli iterano più velocemente quando i risultati sembrano stato UI, non un post di testo libero.

Comportamento play-mode limitato

Il play mode è dove inizia metà dei ticket “l’AI ha rotto il mio progetto”. Le nostre regole:

Modalità	Consentito	Bloccato o limitato
Edit	Mutazioni scena, query risorse	Eliminazioni distruttive del progetto senza conferma
Play	Per lo più lettura / query nodi runtime	Modifiche strutturali alla scena modificata
Transizione	Suggerimenti di attesa / riprova	No-op silenziosi

Errori chiari battono l’astuzia. Se il modello non può modificare durante il play, la risposta MCP lo dice in forma strutturata—così il client può dire all’utente di fermare il play, poi riprovare.

Problemi Difficili che Abbiamo Incontrato (e Mantenuto)

1. L’editor non è un database

L’ordine dei nodi, le relazioni di proprietà e le scene impacchettate interagiscono in modi che sembrano semplici in una GIF e disordinati in un .tscn. Ci siamo affidati alle API di Godot stesse (Node, EditorInterface, caricatori di risorse) piuttosto che inventare un modello di scena parallelo che si sarebbe discostato.

2. Script vs scene come due fonti di verità

Allegare uno script non è la stessa cosa che assicurarsi che lo script compili e che il nome della classe si risolva. Il server riporta separatamente gli esiti di compilazione/allegamento. Questo ha fermato una classe di fallimenti “lo strumento ha detto successo, l’ispettore non mostra nulla”.

3. Sessioni multi-finestra / multi-progetto

Gli sviluppatori aprono più di un’istanza di Godot. Il bridge si lega a un ID sessione editor esplicito così che le chiamate strumento non finiscano nel progetto sbagliato dopo un weekend di sonno + riapertura.

4. Confini di sicurezza

Un server MCP che può riscrivere scene è potente. Trasporto local-first, allowlist esplicite degli strumenti e nessuna esfiltrazione silenziosa nel cloud dell’intero albero del progetto sono non negoziabili. “Assistente AI” e “shell remota sul tuo gioco” devono rimanere categorie di prodotto distinte.

Come si Integra con AI Studio e il Resto di VberAI

Godot MCP è l’operatore del motore. Pezzi complementari:

• VberAI Studio (AI Studio) — struttura design-to-engine per Figma/PSD → gerarchie di controllo; MCP poi collega i pulsanti e rinomina i nodi dopo l’importazione
• Unity MCP / Cocos MCP — stessa idea MCP, diversi host editor e regole di sicurezza
• AI Super Matting — pulisce l’alfa prima che le texture diventino risorse del motore che MCP assegna successivamente

La tesi condivisa: l’AI dovrebbe toccare la superficie di produzione viva (editor, asset, scene), non solo il repository come testo.

Suggerimenti Pratici se Stai Costruendo il Tuo MCP per Motori

1. Accoda le mutazioni sul thread principale del motore — non fingere mai che i motori di gioco siano server shared-nothing
2. Preferisci strumenti piccoli con schemi — la validazione batte la poesia dei prompt
3. Restituisci NodePath e tipi, non prosa — i modelli hanno bisogno di handle operabili
4. Codifica le modalità play/edit in ogni risposta — l’ambiguità qui distrugge la fiducia
5. Misura il round-trip fino a “visibile nel dock” — non solo il tempo di codifica JSON

Se ottimizzi solo il processo MCP e ignori il bridge dell’editor, spedirai un ciclo di allucinazioni veloce.

Conclusione

Costruire un server MCP in tempo reale per Godot ha significato trattare l’editor come un collaboratore vivo: un bridge in coda, sicuro sul thread principale; strumenti modellati come azioni dell’editor; e onestà sui limiti del play mode. MCP solo file è più facile—e incompleto per lavoro nativo delle scene.

Vuoi il percorso già pronto invece di un prototipo del weekend? Inizia con VberAI Godot MCP, connetti il tuo client MCP preferito e prova una prima chiamata strumento banale: elenca il scene tree corrente, poi crea un nodo sotto la selezione. Quel singolo ciclo—query → muta → vedilo nel dock—è il prodotto. Tutto il resto è ingegneria dell’affidabilità attorno ad esso.