Risoluzione dei Problemi di Connessione Cocos MCP: Cursor Non Mostra cocos-creator

Se dici “Cursor è rotto / non si connette”, parti dai sintomi in Cursor: Cursor rotto dopo Cocos Creator MCP.

Se non è ancora chiaro cosa fa MCP e come differisce da “Cocos Creator AI”, leggi prima Cos’è Cocos Creator MCP.

Quando si collega Cocos MCP a Cursor (o a un altro client MCP), il blocco usuale non sono i “prompt sbagliati”—è che il ponte non si connette mai: il server dell’editor è giù, o l’IDE AI non elenca mai cocos-creator.

Questa guida segue sintomo → causa → correzione per Creator 2.x e 3.x. Flussi di installazione completi:

• Installazione Cocos Creator 3.x MCP
• Installazione Cocos Creator 2.x MCP

Gli esempi usano Cursor; Claude Code, Codex e client simili seguono gli stessi controlli di ricaricamento/configurazione.

Prima: quale livello ha fallito?

Il percorso MCP ha quattro livelli. Un fallimento in qualsiasi livello appare come “impossibile connettersi”:

1. Estensione installata e abilitata
        ↓
2. Pannello attivato (account / codice licenza)
        ↓
3. Server MCP mostra In esecuzione (localhost)
        ↓
4. Configurazione IDE AI scritta e elenco MCP mostra connesso

Cosa vedi	Controlla prima
Nessun menu Estensione → Cocos MCP Server / MCP Server	Livello 1: versione pacchetto, percorso di importazione, riavvio
Il pannello si apre ma non può avviarsi / rimane non attivato	Livello 2: account e licenza
Cliccato Avvia ma mai In esecuzione	Livello 3: porta, firewall, attivazione
Creator mostra In esecuzione, Cursor non ha cocos-creator	Livello 4: configurazione rapida, ricaricamento MCP, file di configurazione
Cursor mostra connesso ma non può elencare i nodi della scena	Prompt di verifica, interruttori strumenti, progetto corretto aperto

Sintomo A: Nessuna estensione MCP nel menu

Cause probabili

1. Pacchetti 2.x / 3.x mescolati
2. 3.x: non importato in Gestione Estensioni, o ancora disabilitato
3. 2.x: non sotto packages/<nome-plugin>/, o un livello di annidamento extra dopo l’unzip
4. 2.x: file posizionati ma Creator non riavviato completamente

Correzioni

Creator 3.x:

1. Scarica da Cocos MCP 3.x—non il pacchetto 2.x
2. Apri il progetto → Estensione → Gestione Estensioni → Importa → seleziona lo zip 3.x
3. Conferma che cocos-mcp-server è abilitato; abilitalo se disabilitato
4. Se il menu manca ancora: esci da Creator e riapri lo stesso progetto

Creator 2.x:

1. Scarica da Cocos MCP 2.x
2. Dopo l’unzip, la struttura dovrebbe apparire così:

radice-del-tuo-progetto/
  packages/
    <nome-plugin>/          ← file del plugin direttamente qui
      package.json          ← dovrebbe esistere a questo percorso (nome secondo pacchetto)

3. Annidamento errato esempio:

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

4. Correggi il percorso, poi esci e riavvia Creator (non solo aggiorna la scena). Controlla Estensione → MCP Server.

Sintomo B: Il pannello si apre, ma l’attivazione fallisce o il servizio non si avvia

Cause probabili

• L’account non ha il diritto Pro corrispondente
• Codice licenza scaduto o email non corrispondente
• Cliccato Avvia prima dell’attivazione

Correzioni

1. Apri il pannello MCP (3.x: Estensione → Cocos MCP Server → Apri Pannello MCP; 2.x: Estensione → MCP Server)
2. Attiva con uno dei seguenti:
   • Account VberAI + password
   • Email + codice licenza
3. Conferma piano / codice sul centro account ufficiale, poi riprova nel pannello
4. Solo dopo l’attivazione apri le impostazioni del server MCP e clicca Avvia

Senza attivazione, il server di solito non raggiunge mai In esecuzione. Correggi il lato editor prima di incolpare Cursor.

Sintomo C: Cliccato Avvia, ma mai In esecuzione

Cause probabili

1. Ancora non attivato (vedi sintomo B)
2. Porta in uso (3.x spesso predefinita 3000; 2.x segue il pannello)
3. Firewall / software di sicurezza blocca l’ascolto su localhost

Correzioni

1. Annota la porta sulla pagina delle impostazioni del server MCP (esempi sotto usano 3000—sostituisci con il valore del tuo pannello)
2. Controlla se qualcosa è già in ascolto:

macOS / Linux:

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell):

netstat -ano | findstr :3000

3. Se un altro processo occupa la porta:
   • ferma quel processo, oppure
   • scegli una porta libera nel pannello MCP, poi Avvia di nuovo
4. Assicurati che il firewall permetta 127.0.0.1 (non esporre MCP a internet pubblico)
5. Quando il pannello mostra In esecuzione, configura l’IDE AI

Sintomo D: Creator è In esecuzione, Cursor non ha cocos-creator

La maggior parte dei rapporti di “connessione fallita” si ferma qui: editor OK, client non ha mai ingerito la configurazione.

Correzioni (in ordine)

1. In Creator, conferma che il pannello MCP sia ancora In esecuzione (cambi di porta o riavvii dell’editor possono fermarlo)
2. Apri Gestione Strumenti e abilita gli strumenti necessari
3. Apri Configurazione Rapida → scegli Cursor → Configurazione Automatica finché l’interfaccia non mostra Configurato
4. In Cursor → elenco MCP / strumenti:
   • Dovresti vedere cocos-creator (o il nome mostrato nel pannello)
   • Se manca: Ricarica MCP (o riavvia Cursor) e controlla di nuovo
5. Ancora manca: verifica che la configurazione MCP di Cursor contenga il ponte locale (127.0.0.1 + porta del pannello)

L’output della Configurazione Automatica varia a seconda della versione di Cursor. Quando ispezioni manualmente:

• Il nome del servizio corrisponde a Cocos MCP (es. cocos-creator)
• L’host è 127.0.0.1 o localhost, la porta corrisponde a Creator
• Non un IP LAN o pubblico per errore

Dopo qualsiasi modifica alla configurazione, ricarica MCP di nuovo o l’interfaccia mantiene lo stato vecchio.

Altri IDE AI

In Configurazione Rapida, scegli Claude Code, Codex, Windsurf, Cline, ecc., poi Configurazione Automatica → ricarica MCP in quel client. Configurare Cursor non collega ogni IDE.

Sintomo E: Mostra connesso, ma non può elencare la scena / modificare i nodi

Cause probabili

1. Il progetto / scena aperto in Creator non corrisponde a ciò che hai chiesto
2. Strumenti necessari non selezionati in Gestione Strumenti
3. Hai verificato solo “file su disco,” non contesto editor

Verifica

Invia un prompt sola lettura in Cursor:

Elenca i nomi dei nodi radice della scena attualmente aperta in Cocos Creator.

Risultato	Significato
Corrisponde alla Gerarchia	Ponte OK; prova una piccola scrittura dopo
Errore chiaro / nessuno strumento	Torna ai sintomi C/D
Nomi di nodi inventati	MCP probabilmente non usato; controlla connessione e interruttori strumenti

Poi prova una piccola scrittura (crea un nodo temporaneo e cancellalo). Fai commit prima di modifiche grandi.

Tabella rapida 2.x vs 3.x

Elemento	Creator 3.x	Creator 2.x
Pagina prodotto	cocos (3.x)	cocos2x
Installazione	Gestione Estensioni → Importa	Decomprimi in packages/ del progetto
Dopo installazione	Abilita nell’elenco	Devi riavviare Creator
Pacchetto	Solo 3.x	Solo 2.x
Passi completi	Installazione 3.x	Installazione 2.x

Pacchetti mescolati spesso mostrano “nessun menu” o “importazione fallita”—usa questa tabella prima.

Ordine consigliato (checklist di 5 minuti)

Spunta in ordine; la maggior parte dei fallimenti si trova nei primi quattro:

1. La versione principale di Creator corrisponde allo zip MCP (2.x ↔ 2.x, 3.x ↔ 3.x)
2. Estensione abilitata / percorso packages corretto; 2.x riavviato
3. Pannello attivato con successo
4. Pannello mostra In esecuzione; porta libera
5. Configurazione Rapida → Configurazione Automatica per l’IDE corrente
6. Ricaricato MCP nell’IDE AI; cocos-creator elencato
7. Prompt sola lettura elenca le radici della scena attualmente aperta

Se fallisce ancora, cattura questo

Quando chiedi supporto o a un collega, includi:

• Versione esatta di Creator (es. 3.8.x / 2.4.x)
• Tipo di pacchetto MCP (2.x o 3.x Pro)
• Se il pannello è In esecuzione, e la porta
• Nome/versione IDE AI e screenshot dell’elenco MCP
• Prompt esatto di sola lettura e risposta

Mantieni il ponte solo su localhost; non pubblicare la porta MCP.

Documenti correlati

• Installazione Cocos Creator 3.x MCP
• Installazione Cocos Creator 2.x MCP
• Video configurazione Cocos Creator MCP
• Guida alla scelta del motore: Godot MCP vs Unity MCP vs Cocos MCP