# Pubblica giochi dalla tua app di IA con PlayDrop MCP Come le app di IA pubblicano su PlayDrop tramite MCP: percorso semplice e pacchetti, test privati, publish_game_version, aggiornamenti, limiti e recupero. Source: https://www.playdrop.ai/it/create/learn/mcp-publishing Il server MCP di PlayDrop permette a un’app di IA di pubblicare un gioco sull’account PlayDrop del suo utente e di restituire un link che continua a funzionare anche dopo gli aggiornamenti. Questa guida indica l’ordine delle operazioni. Ogni passaggio rimanda alla guida con i dettagli. ## Prima di costruire 1. Chiama `get_documentation({topic:"index"})` e leggi le guide delle funzioni che il gioco userà, prima di scrivere codice. Pianificare fin dall’inizio layout a schermo intero, salvataggi e comandi evita di riscrivere il gioco in seguito. Per le firme esatte dei metodi leggi gli argomenti `sdk-types`, `server-sdk-types` e `shared-types`. 2. Chiama `list_games`. Se il gioco esiste già, lo aggiornerai mantenendo il suo `name`, così conserva il suo link e i suoi giocatori. 3. Scegli il percorso. Un unico file HTML autonomo senza l’SDK di PlayDrop usa [il percorso semplice](https://www.playdrop.ai/it/create/learn/html-games). Tutto il resto, comprese qualsiasi funzione dell’SDK, i contenuti della scheda o un server, usa [un pacchetto](https://www.playdrop.ai/it/create/learn/packaging). Conserva tu il progetto sorgente del creator. PlayDrop riceve solo il risultato compilato: non è un backup del sorgente e non può restituire il codice sorgente. ## Percorso semplice: upload_game Invia `requestId`, l’HTML completo (al massimo 10 MiB, 10.485.760 byte UTF-8) e un mini catalogo. Passa `gameId` per aggiornare un gioco esistente. Le versioni aumentano automaticamente. Vedi [giochi in HTML semplice](https://www.playdrop.ai/it/create/learn/html-games) per i campi. ## Percorso dei pacchetti: prepara, carica, completa Chiama `prepare_catalogue_upload` con `requestId`, `expectedCurrentVersion` e una sola forma di input: - **Cartella:** `catalogue` (il contenuto di catalogue.json) più `files`, un descrittore per file con il suo percorso relativo. Un descrittore contiene `text` in linea, la descrizione di un caricamento firmato, il collegamento a un allegato oppure il `reuse` di un file da una versione conservata. - **ZIP o .play locale:** estrailo in locale, poi invia il catalogo della radice e i descrittori della cartella. Non mettere mai i byte di un archivio in base64 in una chiamata a uno strumento. - **Allegato di ChatGPT:** passa come `archive` lo ZIP o il .play risolto dall’host, con i suoi veri `download_url` e `file_id`. Può arrivare a 20 MiB compresso e richiede catalogue.json nella radice. Per i caricamenti firmati, ogni descrittore fornisce `path`, `contentType`, `sizeBytes`, `sha256` (64 caratteri esadecimali minuscoli) e `md5Base64`, calcolati in locale dai byte esatti. Invia con PUT quei byte a ogni URL restituito con tutte le intestazioni restituite, poi chiama `complete_catalogue_upload` con lo stesso `requestId`. In ChatGPT, i file della cartella possono provenire da allegati collegati per posizione: ``` attachments: [htmlFile, iconFile] files: [{path:"index.html", attachmentIndex:0}, {path:"listing/icon.png", attachmentIndex:1, role:"LISTING", app:"my-game"}] ``` Ogni app richiede una `version` dichiarata, una visibilità (nella richiesta o nell’app) e una voce in `expectedCurrentVersion` con il suo nome come chiave: `null` per crearla, oppure la versione pubblicata attuale da `list_games` per aggiornarla. Un valore non aggiornato viene rifiutato, così un altro caricamento non viene mai sovrascritto per errore. ## Prova in privato, poi rilascia Carica con `visibility: "private"` quando il gioco usa l’SDK o un server, oppure quando il tuo utente vuole provarlo prima. Apri l’`url` della ricevuta per giocare quella versione esatta dentro PlayDrop con il vero host dell’SDK. Le funzioni del server ospitato girano solo sulle versioni caricate, quindi provale in questo modo. Quando funziona, rilascia quella versione esatta con `publish_game_version`, passando `gameId`, `version`, `expectedCurrentVersion` e, se il tuo utente ne ha scelta una, `visibility` (`public` o `unlisted`). Riutilizza i file, la scheda e la revisione già testati. Non caricare di nuovo il gioco per rilasciarlo. Per provare una build locale nel frame di PlayDrop prima di caricarla, apri `https://www.playdrop.ai/@//dev?url=` in un normale browser sul computer su cui gira il server locale. ## Scegli chi può giocare `visibility` accetta `public`, `unlisted` e `private`. Per un nuovo gioco senza una scelta, usa l’impostazione salvata del creator: `upload_game` la applica quando ometti la visibilità, e `get_account` la mostra come `publishing.defaultVisibility`. Per un aggiornamento, mantieni il `gameVisibility` del gioco da `list_games`, a meno che il tuo utente non lo cambi; `upload_game` lo fa quando ometti la visibilità, mentre un pacchetto la indica esplicitamente. Non in elenco significa che chiunque abbia il link può giocare; non è una lista di amici. Non rendere mai un gioco più visibile di quanto il tuo utente volesse. Dettagli: [chi può giocare](https://www.playdrop.ai/it/create/learn/distribution). ## Consegna il link giusto Le ricevute dei giochi pubblici e non in elenco includono `shareUrl`, la pagina duratura del gioco: consegna quello al tuo utente. Una versione privata restituisce `url`, il link della versione esatta per il proprietario. Le ricevute dei pacchetti elencano ogni elemento; gli elementi completati restano pubblicati anche se un elemento successivo non riesce. ## Aggiorna un gioco Leggi `list_games` e la versione attuale, mantieni il `name` e invia un’istantanea completa: tutti i file previsti e tutti i metadati previsti, perché i campi omessi mancano nella nuova versione. Le voci del catalogo omesse non vengono mai eliminate. Usa `get_game_version` per leggere il catalogo esatto della versione che stai modificando, compreso lo stato dei valori regolabili. ## Limiti - Percorso semplice: un file HTML di al massimo 10 MiB. - Pacchetto: 512 descrittori di file della cartella o 512 voci dell’archivio (compresi catalogue.json e le cartelle), 50 MiB per file, 200 MiB estratti in totale e 1 MiB di JSON del catalogo. - Archivi: solo percorsi relativi sicuri; vengono rifiutati percorsi duplicati, link simbolici e archivi cifrati, multiparte e ZIP64. - I caricamenti preparati scadono dopo 30 minuti. ## Errori e nuovi tentativi Gli errori contengono `error`, `message`, `retryable`, `nextAction`, `docsUrl` e `documentationTopic`. Segui `nextAction`. Dopo una risposta persa, riprova con contenuto identico e lo stesso `requestId`; un contenuto modificato ne richiede uno nuovo. Vedi [errori e recupero](https://www.playdrop.ai/it/create/learn/errors). Usa `send_feedback` per segnalare un problema riproducibile o un passaggio poco chiaro, senza token né URL firmati. ## Guide correlate - [Giochi in HTML semplice](https://www.playdrop.ai/it/create/learn/html-games): Pubblica un file HTML autonomo fino a 10 MiB con upload_game: cosa ci sta, il mini catalogo, la visibilità, gli aggiornamenti e quando passare a un pacchetto. - [Pacchetti e .play](https://www.playdrop.ai/it/create/learn/packaging): Organizza una cartella compilata, uno ZIP o un .play con catalogue.json nella radice, dichiara scheda e server e caricalo con prepare_catalogue_upload. - [Visibilità e pubblico](https://www.playdrop.ai/it/create/learn/distribution): Scegli chi può aprire un gioco, capisci l’impostazione predefinita e le versioni, e scopri come Boost, Scambio di partite, Instant e ricerca portano giocatori. - [Errori e recupero](https://www.playdrop.ai/it/create/learn/errors): La forma degli errori restituiti dagli strumenti MCP di PlayDrop, quando riprovare con lo stesso requestId e la soluzione per ogni codice di errore comune.