Dépannage de la connexion Cocos MCP : Cursor n'affiche pas cocos-creator

Premièrement : quelle couche a échoué ?

Si vous dites « Cursor est cassé / ne se connecte pas », partez des symptômes côté Cursor : Cursor cassé après Cocos Creator MCP.

Si le rôle de MCP et l’écart avec « Cocos Creator AI » restent flous, lisez d’abord Qu’est-ce que Cocos Creator MCP.

Le chemin MCP comporte quatre couches. Une défaillance à n’importe quelle couche ressemble à « impossible de se connecter » :

1. Extension installée et activée
        ↓
2. Panneau activé (compte / code de licence)
        ↓
3. Serveur MCP affiche En cours d'exécution (localhost)
        ↓
4. Configuration de l'IDE IA écrite et liste MCP affiche connecté

Ce que vous voyez	Vérifiez d’abord
Pas de menu Extension → Cocos MCP Server / MCP Server	Couche 1 : version du paquet, chemin d’importation, redémarrage
Le panneau s’ouvre mais ne peut pas démarrer / reste non activé	Couche 2 : compte et licence
Cliqué sur Démarrer mais jamais En cours d’exécution	Couche 3 : port, pare-feu, activation
Creator affiche En cours d’exécution, Cursor n’a pas cocos-creator	Couche 4 : configuration rapide, rechargement MCP, fichier de configuration
Cursor affiche connecté mais ne peut pas lister les nœuds de scène	Invite de vérification, bascules d’outils, projet ouvert correct

Symptôme A : Pas d’extension MCP dans le menu

Causes probables

1. Paquets mixtes 2.x / 3.x
2. 3.x : non importé dans le gestionnaire d’extensions, ou toujours désactivé
3. 2.x : pas sous packages/<nom-du-plugin>/, ou un niveau d’imbrication supplémentaire lors de la décompression
4. 2.x : fichiers placés mais Creator pas complètement redémarré

Correctifs

Creator 3.x :

1. Téléchargez depuis Cocos MCP 3.x—pas le pack 2.x
2. Ouvrez le projet → Extension → Gestionnaire d’extensions → Importer → sélectionnez le zip 3.x
3. Confirmez que cocos-mcp-server est activé ; activez-le s’il est désactivé
4. Si le menu est toujours manquant : quittez Creator et rouvrez le même projet

Creator 2.x :

1. Téléchargez depuis Cocos MCP 2.x
2. Après décompression, l’arborescence devrait ressembler à :

racine-de-votre-projet/
  packages/
    <nom-du-plugin>/          ← fichiers du plugin directement ici
      package.json          ← devrait exister à ce chemin (nom selon le paquet)

3. Mauvaise imbrication exemple :

packages/
  xxx-mcp-unzip/
    <nom-du-plugin>/
      package.json

4. Corrigez le chemin, puis quittez et redémarrez Creator (pas seulement actualiser la scène). Vérifiez Extension → Serveur MCP.

Symptôme B : Le panneau s’ouvre, mais l’activation échoue ou le service ne démarre pas

Causes probables

• Le compte ne dispose pas de l’entitlement Pro correspondant
• Code de licence expiré ou e-mail ne correspond pas
• Cliqué sur Démarrer avant l’activation

Correctifs

1. Ouvrez le panneau MCP (3.x : Extension → Cocos MCP Server → Ouvrir le panneau MCP ; 2.x : Extension → Serveur MCP)
2. Activez avec soit :
   • Compte VberAI + mot de passe
   • E-mail + code de licence
3. Confirmez le plan / code sur le centre de compte officiel, puis réessayez dans le panneau
4. Après activation uniquement, ouvrez les paramètres du serveur MCP et cliquez sur Démarrer

Sans activation, le serveur n’atteint généralement jamais En cours d’exécution. Corrigez le côté éditeur avant de blâmer Cursor.

Symptôme C : Cliqué sur Démarrer, mais jamais En cours d’exécution

Causes probables

1. Toujours pas activé (voir symptôme B)
2. Port utilisé (3.x utilise souvent par défaut 3000 ; 2.x suit le panneau)
3. Pare-feu / logiciel de sécurité bloque l’écoute localhost

Correctifs

1. Notez le port sur la page des paramètres du serveur MCP (les exemples ci-dessous utilisent 3000—remplacez par la valeur de votre panneau)
2. Vérifiez si quelque chose écoute déjà :

macOS / Linux :

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell) :

netstat -ano | findstr :3000

3. Si un autre processus occupe le port :
   • arrêtez ce processus, ou
   • choisissez un port libre dans le panneau MCP, puis Démarrer à nouveau
4. Assurez-vous que le pare-feu autorise 127.0.0.1 (ne pas exposer MCP à l’internet public)
5. Lorsque le panneau affiche En cours d’exécution, configurez l’IDE IA

Symptôme D : Creator est en cours d’exécution, Cursor n’a pas cocos-creator

La plupart des rapports de « échec de connexion » arrivent ici : éditeur OK, client n’a jamais ingéré la configuration.

Correctifs (dans l’ordre)

1. Dans Creator, confirmez que le panneau MCP est toujours En cours d’exécution (les changements de port ou les redémarrages de l’éditeur peuvent l’arrêter)
2. Ouvrez le Gestionnaire d’outils et activez les outils dont vous avez besoin
3. Ouvrez Configuration rapide → choisissez Cursor → Configuration automatique jusqu’à ce que l’interface affiche Configuré
4. Dans Cursor → liste MCP / outils :
   • Vous devriez voir cocos-creator (ou le nom affiché dans le panneau)
   • Si manquant : Recharger MCP (ou redémarrer Cursor) et vérifiez à nouveau
5. Toujours manquant : vérifiez que la configuration MCP de Cursor contient le pont local (127.0.0.1 + le port du panneau)

La sortie de la configuration automatique varie selon la version de Cursor. Lors d’une inspection manuelle :

• Le nom du service correspond à Cocos MCP (par exemple cocos-creator)
• L’hôte est 127.0.0.1 ou localhost, le port correspond à Creator
• Pas une IP LAN ou publique par erreur

Après toute modification de configuration, rechargez MCP à nouveau ou l’interface conservera l’ancien état.

Autres IDE IA

Dans la configuration rapide, choisissez Claude Code, Codex, Windsurf, Cline, etc., puis Configuration automatique → recharger MCP dans ce client. Configurer Cursor ne connecte pas chaque IDE.

Symptôme E : Affiche connecté, mais ne peut pas lister la scène / modifier les nœuds

Causes probables

1. Le projet / la scène ouvert dans Creator ne correspond pas à ce que vous avez demandé
2. Les outils nécessaires ne sont pas cochés dans le Gestionnaire d’outils
3. Vous avez seulement vérifié « les fichiers sur le disque », pas le contexte de l’éditeur

Vérification

Envoyez une invite en lecture seule dans Cursor :

Listez les noms des nœuds racines de la scène actuellement ouverte dans Cocos Creator.

Résultat	Signification
Correspond à la hiérarchie	Pont OK ; essayez une petite écriture ensuite
Erreur claire / pas d’outils	Revenez aux symptômes C/D
Noms de nœuds inventés	MCP probablement non utilisé ; vérifiez la connexion et les bascules d’outils

Ensuite, essayez une petite écriture (créez un nœud temporaire et supprimez-le). Validez avant les grandes modifications.

Tableau rapide 2.x vs 3.x

Élément	Creator 3.x	Creator 2.x
Page produit	cocos (3.x)	cocos2x
Installation	Gestionnaire d’extensions → Importer	Décompressez dans le projet packages/
Après installation	Activez dans la liste	Doit redémarrer Creator
Paquet	3.x uniquement	2.x uniquement
Étapes complètes	Installation 3.x	Installation 2.x

Les paquets mixtes apparaissent souvent comme « pas de menu » ou « échec d’importation »—utilisez ce tableau en premier.

Ordre recommandé (liste de contrôle de 5 minutes)

Cochez dans l’ordre ; la plupart des échecs se situent dans les quatre premiers :

1. La version majeure de Creator correspond au zip MCP (2.x ↔ 2.x, 3.x ↔ 3.x)
2. Extension activée / chemin packages correct ; 2.x redémarré
3. Panneau activé avec succès
4. Panneau affiche En cours d’exécution ; port libre
5. Configuration rapide → Configuration automatique pour l’IDE actuel
6. MCP rechargé dans l’IDE IA ; cocos-creator listé
7. Invite en lecture seule liste les racines de la scène actuellement ouverte

Si cela échoue encore, capturez ceci

Lorsque vous demandez de l’aide au support ou à un collègue, incluez :

• Version exacte de Creator (par exemple 3.8.x / 2.4.x)
• Type de pack MCP (2.x ou 3.x Pro)
• Si le panneau est En cours d’exécution, et le port
• Nom/version de l’IDE IA et capture d’écran de la liste MCP
• Invite en lecture seule exacte et réponse

Gardez le pont sur localhost uniquement ; ne publiez pas le port MCP.

Documentation connexe

• Installation de Cocos Creator 3.x MCP
• Installation de Cocos Creator 2.x MCP
• Guide vidéo de configuration de Cocos Creator MCP
• Guide de choix de moteur : Godot MCP vs Unity MCP vs Cocos MCP