Comment nous avons construit un serveur MCP en temps réel pour Godot

Pourquoi le « temps réel » est important pour un serveur MCP dans Godot

La plupart des démos MCP fonctionnent dans un monde de type REST : le modèle pose une question, un outil renvoie du JSON, et personne ne se soucie si l’aller-retour a pris deux secondes. Godot est différent. L’éditeur possède un arbre de scène vivant, des imports de ressources et une boucle de mode lecture. Si votre serveur MCP bloque le thread principal—ou ne voit qu’un dump obsolète du projet—les clients IA cessent de ressembler à des copilotes et commencent à ressembler à des éditeurs de fichiers distants avec des étapes supplémentaires.

Lorsque nous avons conçu Godot MCP pour VberAI, le cahier des charges était explicite :

• Un assistant IA (Cursor, Claude, Windsurf, et autres clients MCP) doit opérer l’éditeur, pas seulement lire des fichiers .gd depuis le disque
• Des actions comme créer un nœud, renommer, attacher un script et interroger la sélection doivent s’exécuter pendant que l’éditeur reste réactif
• Les contextes mode lecture et mode édition doivent rester honnêtes—les outils doivent échouer bruyamment lorsqu’une opération est dangereuse en cours de lecture

Ce post est l’histoire d’ingénierie : comment nous avons construit un serveur MCP en temps réel qui se tient à côté de Godot au lieu de prétendre que le projet est un dépôt statique.

Le problème du MCP « fichiers uniquement » pour les moteurs

Une approche naïve est tentante :

1. Pointer le serveur MCP vers le dossier du projet
2. Exposer read_file / write_file / list_dir
3. Laisser le modèle inventer du GDScript et espérer que l’éditeur recharge proprement

Cela fonctionne pour les sites de documentation. Cela échoue pour le travail sur moteur car :

• La propriété de la scène vit en mémoire — les diffs .tscn non sauvegardés, les scènes ouvertes et la sélection de l’éditeur sont invisibles sur le disque
• Les pipelines d’import sont étatiques — écrire un PNG n’est pas la même chose que « ressource prête avec les bons réglages d’import »
• Les signaux et les chemins de nœuds sont des données de graphe — les modifications de chaînes cassent silencieusement le câblage
• La latence se cumule — chaque confirmation « le nœud est-il apparu ? » devient un autre scan complet du système de fichiers

Nous avions besoin d’une surface MCP qui reflète ce qu’un humain voit déjà dans le dock Godot : hiérarchie, propriétés en forme d’inspecteur, et poignées de ressources—pas seulement des chaînes de chemins.

Vue d’ensemble de l’architecture

À un niveau élevé, Godot MCP est trois couches coopérantes :

Client MCP (Cursor / Claude / …)
        │  JSON-RPC sur stdio ou transport local
        ▼
Serveur MCP (processus de pont VberAI Godot)
        │  file de commandes + enveloppes de résultats
        ▼
Plugin éditeur Godot (GDExtension / plugin éditeur)
        │  appels différés sur le thread principal
        ▼
Arbre de scène de l'éditeur / ResourceDB / Éditeur de script

Couche 1 — Surface d’outils MCP

Les outils sont intentionnellement petits et en forme de verbe :

• godot_get_scene_tree — instantané de la scène éditée avec les types de nœuds et les chemins
• godot_create_node / godot_set_property
• godot_attach_script / godot_run_script_snippet (protégé)
• godot_list_resources / godot_get_selection

Nous évitons un outil géant do_anything. Les petits outils sont plus faciles à valider, plus faciles à journaliser, et plus difficiles à abuser par un modèle pour des patchs illimités.

Couche 2 — le pont temps réel

C’est là que le « temps réel » vit réellement :

• Un canal bidirectionnel entre le processus MCP et le plugin éditeur (socket local ou pipe nommé en développement ; les builds produits peuvent l’envelopper derrière l’assistant de bureau VberAI)
• Une file de commandes qui sérialise les mutations afin que deux appels d’outils qui se chevauchent ne puissent pas faire la course avec l’arbre de scène
• Identifiants de requête + accusés de réception pour que le client MCP puisse attendre « appliqué » sans interroger le système de fichiers
• Battement de cœur / vivacité de l’éditeur pour que les clients sachent quand Godot a quitté en cours de session

Couche 3 — Sécurité du thread principal dans Godot

Les API d’interface utilisateur et de scène de Godot ne sont pas librement threadées. Le plugin ne mute jamais les nœuds sur le thread d’E/S MCP. Au lieu de cela :

1. La commande MCP arrive sur le thread du pont
2. La charge utile est mise en file
3. Le rappel différé de l’éditeur s’exécute sur le thread principal (call_deferred / hook de frame idle)
4. L’enveloppe de résultat renvoie succès, erreur structurée, ou « réessayez après la fin du mode lecture »

Ce modèle est ennuyeux par conception. L’ennui est ce qui empêche le « temps réel » de devenir des « gelées aléatoires de l’éditeur ».

Le rendre réellement temps réel (sans mentir sur la latence)

« Temps réel » ici ne signifie pas une latence zéro magique. Cela signifie que la boucle de rétroaction correspond à la façon dont les humains travaillent dans l’éditeur.

Instantané vs flux

Les premiers prototypes renvoyaient l’arbre de scène entier à chaque appel. Cela s’effondrait sur les grandes configurations de monde ouvert. Nous sommes passés à :

• Instantanés peu profonds par défaut (racine + un niveau, ou axés sur la sélection)
• Lectures limitées au chemin lorsque le modèle connaît déjà une sous-arborescence
• Jetons de changement optionnels pour que les appels suivants puissent demander « qu’est-ce qui a changé depuis X ? » au lieu de tout resérialiser

Résultats favorables aux diffs

Les résultats d’outils incluent :

• Chaînes NodePath canoniques
• Noms de types (CharacterBody2D, Control, …)
• Clés de propriétés qui correspondent proprement aux champs de l’inspecteur
• Avertissements explicites lorsqu’une écriture a été appliquée mais que la scène est toujours sale / non sauvegardée

Les modèles itèrent plus vite lorsque les résultats ressemblent à l’état de l’interface utilisateur, pas à un article de blog de texte libre.

Comportement borné en mode lecture

Le mode lecture est là où la moitié des tickets « l’IA a cassé mon projet » commencent. Notre ensemble de règles :

Mode	Autorisé	Bloqué ou conditionné
Édition	Mutations de scène, requêtes de ressources	Suppressions destructrices de projet sans confirmation
Lecture	Principalement lecture / requêtes de nœuds runtime	Modifications structurelles de la scène éditée
Transition	Indices d’attente / réessai	Non-ops silencieux

Des erreurs claires valent mieux que de l’ingéniosité. Si le modèle ne peut pas éditer pendant la lecture, la réponse MCP le dit sous forme structurée—afin que le client puisse dire à l’utilisateur d’arrêter la lecture, puis de réessayer.

Problèmes difficiles que nous avons rencontrés (et gardés)

1. L’éditeur n’est pas une base de données

L’ordre des nœuds, les relations de propriétaire et les scènes empaquetées interagissent d’une manière qui semble simple dans un GIF et désordonnée dans un .tscn. Nous nous sommes appuyés sur les propres API de Godot (Node, EditorInterface, chargeurs de ressources) plutôt que d’inventer un modèle de scène parallèle qui dériverait.

2. Scripts vs scènes comme deux sources de vérité

Attacher un script n’est pas la même chose que s’assurer que le script compile et que le nom de classe se résout. Le serveur signale les résultats de compilation/attachement séparément. Cela a arrêté une classe d’échecs « l’outil a dit succès, l’inspecteur ne montre rien ».

3. Sessions multi-fenêtres / multi-projets

Les développeurs ouvrent plus d’une instance Godot. Le pont se lie à un identifiant de session d’éditeur explicite afin que les appels d’outils n’atterrissent pas dans le mauvais projet après un week-end de sommeil + réouverture.

4. Frontières de sécurité

Un serveur MCP qui peut réécrire des scènes est puissant. Transport local d’abord, listes d’autorisation d’outils explicites, et aucune exfiltration cloud silencieuse de l’arbre complet du projet sont non négociables. « Assistant IA » et « shell distant sur votre jeu » doivent rester des catégories de produits distinctes.

Comment cela s’intègre à côté d’AI Studio et du reste de VberAI

Godot MCP est l’opérateur de moteur. Pièces complémentaires :

• VberAI Studio (AI Studio) — structure design-vers-moteur pour Figma/PSD → hiérarchies de contrôle ; MCP câble ensuite les boutons et renomme les nœuds après l’import
• Unity MCP / Cocos MCP — même idée MCP, différents hôtes d’éditeur et règles de sécurité
• AI Super Matting — nettoie l’alpha avant que les textures deviennent des ressources moteur que le MCP assigne plus tard

La thèse commune : l’IA doit toucher la surface de production vivante (éditeur, assets, scènes), pas seulement le dépôt en tant que texte.

Conseils pratiques si vous construisez votre propre MCP de moteur

1. Mettez en file les mutations sur le thread principal du moteur — ne prétendez jamais que les moteurs de jeu sont des serveurs sans état partagé
2. Préférez les petits outils avec des schémas — la validation bat la poésie de prompt
3. Renvoiez des NodePaths et des types, pas de la prose — les modèles ont besoin de poignées opérationnelles
4. Encodez les modes lecture/édition dans chaque réponse — l’ambiguïté ici détruit la confiance
5. Mesurez l’aller-retour jusqu’à « visible dans le dock » — pas seulement le temps d’encodage JSON

Si vous n’optimisez que le processus MCP et ignorez le pont d’éditeur, vous livrerez une boucle d’hallucination rapide.

Conclusion

Construire un serveur MCP en temps réel pour Godot signifiait traiter l’éditeur comme un collaborateur vivant : un pont mis en file, sûr pour le thread principal ; des outils en forme d’actions d’éditeur ; et l’honnêteté sur les limites du mode lecture. Le MCP fichiers uniquement est plus facile—et incomplet pour le travail natif de scène.

Vous voulez le chemin livré au lieu d’un prototype de week-end ? Commencez avec VberAI Godot MCP, connectez votre client MCP préféré, et essayez un premier appel d’outil trivial : listez l’arbre de scène actuel, puis créez un nœud sous la sélection. Cette boucle unique—interroger → muter → le voir dans le dock—est le produit. Tout le reste est de l’ingénierie de fiabilité autour.