Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Test e debug

Lezione 9 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Test a strati
  2. Il server MCP
  3. Il plugin completo
  4. Diagnosticare per strato
  5. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base delle pagine Connect and test your plugin e Troubleshooting della documentazione dei plugin OpenAI. Il precedente “development playground” e i relativi comandi appartenevano all’SDK inesistente della prima versione di questo corso. Fonti: Connect and test · Troubleshooting.

Test a strati

OpenAI consiglia di testare ogni singola funzionalità prima di distribuire l’intero plugin installato: prima il server MCP standalone connesso a ChatGPT, poi il plugin confezionato con le sue competenze. Mantieni i tuoi prompt di valutazione e i relativi risultati per tutto lo sviluppo, in modo da poter confrontare il comportamento tra le diverse versioni.

Il server MCP

Preparare l’endpoint

Prima di testare in ChatGPT, verifica che il server sia raggiungibile tramite HTTPS pubblico (o attraverso un Secure MCP Tunnel), che parli streamable HTTP (tipicamente su /mcp), che nomi degli strumenti, descrizioni, schemi e annotazioni siano presenti e che il rilevamento dell’autenticazione funzioni per gli strumenti che richiedono un account. Un tunnel di sviluppo va bene per le prove, ma non per la sottomissione.

Ispezionare

MCP Inspector chiama i tuoi strumenti direttamente, senza un modello:

npx @modelcontextprotocol/inspector@latest

Sottoponi ogni strumento a tutti i test possibili: input rappresentativi, casi limite, credenziali mancanti e risultati vuoti. Controlla la validazione dello schema, gli errori di autenticazione, le annotazioni, il comportamento di conferma e l’output leggibile dal modello.

Valutare la selezione degli strumenti

Una volta connesso il server come plugin personale (Lezione 4), installalo, apri una nuova conversazione, digita @ e selezionalo. Costruisci un set di valutazione contenente:

  • Richieste dirette che dovrebbero attivare uno strumento specifico;
  • Richieste indirette che esprimono lo stesso obiettivo in modo diverso;
  • Richieste di follow-up che riutilizzano identificatori ottenuti in precedenza;
  • Operazioni di scrittura che richiedono autorizzazione o conferma;
  • Richieste fuori scope che non dovrebbero attivare alcuno strumento.

Per ciascuna, registra lo strumento selezionato, i suoi argomenti, il risultato, eventuali errori e il comportamento di conferma. Ripeti l’intero set ogni volta che modifichi un nome, una descrizione, uno schema o un’annotazione. Se il server restituisce un componente UI, testa sia il componente stesso sia il risultato leggibile dal modello.

Visualizzare gli scambi grezzi

Per leggere richieste e risposte complete, l’API Playground accetta un server MCP: vai su Tools → Add → MCP Server, inserisci l’indirizzo HTTPS, connettiti, quindi esegui i tuoi prompt di test.

Aggiornare i metadati

Dopo qualsiasi modifica a un nome, descrizione, schema, annotazione, metodo di autenticazione o risorsa UI: ridistribuisci o riavvia il server, apri la connessione su chatgpt.com/plugins, seleziona Refresh, verifica che i metadati pubblicizzati siano cambiati e ripeti i test pertinenti in una nuova conversazione. Questo aggiornamento si applica ai server connessi direttamente; per un plugin pubblicato, gli aggiornamenti degli strumenti rientrano nella revisione continua (Lezione 11).

Prima del confezionamento, verifica che l’elenco degli strumenti corrisponda alle funzionalità pubblicizzate, che i risultati strutturati siano conformi agli schemi di output, che i fallimenti di autenticazione restituiscano errori utili, che i prompt corretti attivino gli strumenti giusti mentre quelli sbagliati non ne attivino nessuno e che l’UI venga renderizzata senza errori nella console, ripristinando correttamente il proprio stato.

Il plugin completo

Una volta pronto il server (o immediatamente per un plugin costituito solo da competenze), confeziona il plugin (Lezione 10), aggiungilo a un marketplace locale, installalo dalla directory dei plugin, quindi ripeti le richieste dal tuo inventario di casi d’uso: dirette, indirette, di follow-up, negative e casi limite intenzionalmente esclusi. Verifica che il plugin segua le istruzioni delle competenze, utilizzi le risorse corrette, completi ogni passaggio e produca un risultato utile; che le competenze chiamino gli strumenti corretti e che l’autenticazione funzioni dopo l’installazione.

Diagnosticare per strato

Quando qualcosa non funziona, inizia isolando lo strato difettoso: server, componente o client ChatGPT.

SintomoIndagine
Nessuno strumento elencatoIl server è in esecuzione? L’indirizzo termina con /mcp?
Dati strutturati, ma nessun componenteLo strumento include _meta.ui.resourceUri che punta a una risorsa registrata di tipo text/html;profile=mcp-app che si carica senza errori CSP?
Errori di schemaI tuoi modelli Python o TypeScript corrispondono all’outputSchema pubblicizzato?
Componente lentoLe chiamate agli strumenti superano alcune centinaia di millisecondi? Profila e usa la cache.
Il componente non si caricaConsole del browser: violazione CSP, bundle incompleto?
Stato perso (drag-and-drop, modifica)Chiama window.openai.setWidgetState dopo ogni aggiornamento e ripristina da window.openai.widgetState al montaggio.
Layout rotto su mobileLeggi window.openai.displayMode e window.openai.maxHeight; evita altezze fisse e azioni al passaggio del mouse.
Strumento mai selezionatoRiscrivi la descrizione come “Usa quando…”, rivedi i prompt iniziali.
Strumento sbagliato selezionatoChiarisci gli strumenti vicini, specifica i casi esclusi, dividi gli strumenti troppo ampi.
Errori 401Includi WWW-Authenticate nella risposta; verifica issuer e audience.
invalid_client su una connessione esistenteIl client OAuth registrato esiste ancora? Ripristinalo invece di crearne uno nuovo.
Il tunnel ngrok scadeRiavvialo, verifica che il server locale sia in esecuzione; in produzione, usa un hosting stabile con health probe.
Streaming interrotto dietro un proxyIl load balancer o la CDN devono far passare lo streaming HTTP senza buffering.

Se il problema persiste, raccogli i log del server, la console del componente, una trascrizione delle chiamate agli strumenti e screenshot. Annota il prompt utilizzato e invia tutto al tuo contatto presso OpenAI.

Punti chiave

  • Testa a strati: server da solo (Inspector, poi ChatGPT), quindi il plugin completo
  • Costruisci un set di valutazione: richieste dirette, indirette, di follow-up, di scrittura e fuori scope
  • L’API Playground mostra gli scambi MCP grezzi
  • Esegui Refresh dopo ogni modifica ai metadati, quindi avvia una nuova conversazione
  • In caso di problemi, isola prima lo strato: server, componente o client