--- title: "Strumenti" description: "Gli strumenti che un agente può usare per creare, modificare e pubblicare un sito, e le autorizzazioni necessarie per ciascuno." canonical: "https://atelier201.com/docs/it/mcp/standard-tools" updated: "2026-11-06" --- # Strumenti La [copertura delle operazioni generate](/docs/api/surfaces) mappa REST, CLI e MCP. Per individuarle, leggi `atelier201://operations`, poi `atelier201://operations/{operation_id}` per consultare un contratto completo. Il documento completo è `atelier201://openapi`. Gli argomenti degli strumenti non riconosciuti vengono rifiutati, anziché ignorati senza avviso. `get_workspace` legge i file non ancora sottoposti a commit e le differenze senza eseguire bash. Usa lo stesso permesso `sites:write` dell'endpoint REST del workspace e non modifica né la bozza né il sito pubblicato. Gli strumenti sono pensati per le attività che svolge un agente, non per gli endpoint. Le loro descrizioni sono scritte a mano perché per un modello costituiscono l'intera interfaccia: ognuna indica cosa modifica, se le modifiche sono visibili ai visitatori e quale strumento chiamare dopo. Vengono proposti solo gli strumenti consentiti dagli ambiti della tua credenziale, quindi una connessione senza `sites:publish` non vedrà mai `publish_site`. Uno strumento consuma crediti: `generate_media`, e solo con il permesso `media:generate`. ## Sequenza di lavoro 1. `get_account`, poi `list_sites` per ottenere un `site_id`, oppure `create_site`. 2. `edit_text` per qualsiasi testo visibile, `set_field` per un campo già individuato, `save_entry` e `save_entries` per le voci, `save_singleton theme` per l'aspetto. Usa `read_file` e `edit_files` (oppure `bash` e poi `commit_workspace`) solo per modificare il codice. 3. Ogni salvataggio avvia una build e restituisce `build`: `get_build` con quell'ID attende (50 s per impostazione predefinita) e risponde quando lo stato è `ready` o `failed`. Con `preview: true`, una build pronta include un link da aprire; se non hai un browser, `read_page` legge le pagine. `build_site` serve per creare una build di una determinata revisione o riprovare. 4. `show_site`: in un host che visualizza app (Claude, ChatGPT), il proprietario vede la bozza in tempo reale in una scheda, con il pulsante Publish. Negli altri casi, usa `share_preview` e inviagli il link. 5. `review_publish`, poi `publish_site` solo dopo l'approvazione del proprietario. ## Siti e contenuti | Strumento | Ambito | Funzione | | --------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_sites`, `get_site` | `sites:read` | Leggono i siti del workspace. | | `create_site` | `sites:write` | Crea un sito a partire dal modello iniziale e avvia la prima build. | | `rename_site` | `sites:write` | Modifica il nome visualizzato in Atelier201. | | `get_content_model` | `sites:read` | Legge le raccolte e i singleton con i relativi JSON Schemas. | | `list_entries`, `get_entry` | `sites:read` | Leggono le voci di una raccolta. | | `save_entry` | `sites:write` | Scrive una voce e ne verifica la validità. Una nuova voce viene creata come bozza. | | `delete_entry` | `sites:write` | Rimuove una voce dalla bozza. | | `get_singleton` | `sites:read` | Legge i dettagli dell'attività, il tema o la navigazione. | | `save_singleton` | `sites:write` | Sostituisce un singleton per intero e ne verifica la validità. | | `set_field` | `sites:write` | Modifica un campo tramite il relativo indirizzo `data-atelier201-field`. | | `apply_site_plan` | `sites:write` | Scrive in un'unica chiamata una prima versione o una revisione importante: dettagli dell'attività, tema, navigazione, voci e immagini, verificandone insieme la validità. | | `place_image` | `sites:write` | Inserisce un'immagine in un campo immagine (una descrizione per immagini stock, un risultato selezionato o un file del sito) con il relativo testo alternativo, in un'unica chiamata. | | `edit_text` | `sites:write` | Modifica un testo ovunque sia presente (nei contenuti o nel codice), indicandolo come appare sulla pagina. | ## File, cronologia e changeset | Strumento | Ambito | Funzione | | -------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `list_files`, `read_file`, `read_files`, `search_files` | `sites:read` | Leggono il progetto. `read_file` restituisce l'hash da inviare come `expected_hash`; `read_files` legge fino a 30 file in un'unica chiamata. | | `edit_files` | `sites:write` | Applica operazioni di inserimento, eliminazione e spostamento come una singola voce nella cronologia. | | `get_workspace` | `sites:write` | Legge i file non ancora sottoposti a commit e le relative differenze, senza eseguire comandi. | | `open_changeset`, `stage_changes`, `commit_changeset`, `abandon_changeset` | `sites:write` | Crea una singola voce nella cronologia a partire da più chiamate. | | `list_history`, `compare_revisions` | `sites:read` | Leggono la cronologia. | | `restore_revision` | `sites:write` | Riporta la bozza a una revisione precedente, creando una nuova voce nella cronologia. | ## Contenuti multimediali | Strumento | Ambito | Funzione | | ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------ | | `list_media` | `sites:read` | Legge i file caricati e lo spazio di archiviazione rimanente. | | `upload_media` | `sites:write` | Carica un file base64, fino a un massimo di 5 MB tramite MCP. | | `delete_media` | `sites:write` | Rimuove un file dalle build successive. | | `search_stock_media` | `sites:read` | Cerca foto e video stock gratuiti (Pixabay). | | `import_stock_media` | `sites:write` | Copia un risultato nei contenuti multimediali del sito, con la relativa attribuzione. | | `list_media_models` | `sites:read` | Elenca i modelli AI per immagini e video e i relativi prezzi in crediti. | | `generate_media` | `media:generate` | Crea un'immagine o un video con l'AI. Consuma crediti: prima `estimate_only`, poi `max_credits`. | | `get_media_generation` | `sites:read` | Mostra lo stato di una generazione e, una volta completata, il relativo file. | ## Build e anteprima | Strumento | Ambito | Funzione | | ------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `build_site` | `sites:write` | Compila la bozza. Restituisce subito una build con stato `queued`. | | `list_builds`, `get_build`, `get_build_log` | `sites:read` | Leggono le build e il log di una build non riuscita. `get_build` accetta `wait` (risponde al termine della build) e `preview` (fornisce un link a una build pronta; richiede `sites:write`). | | `read_page` | `sites:read` | Legge una pagina della build come la vede un visitatore, incluse le criticità che emergerebbero da una revisione rapida: per gli agenti senza browser. | | `show_site` | `sites:read` | Apre la scheda del sito, un'app MCP: mostra la bozza in tempo reale (si aggiorna automaticamente dopo ogni build), un'immagine della home page quando l'host non può visualizzarla in un riquadro, il pulsante Publish (Go live, Publish changes) e Comment, che invia alla conversazione la richiesta "change this" relativa a un elemento. Senza `sites:write`, la scheda mostra solo l'immagine. | | `share_preview` | `sites:write` | Crea un link privato a una build, valido 7 giorni per impostazione predefinita. | | `list_previews` | `sites:read` | Legge i link alle anteprime. | | `revoke_preview` | `sites:write` | Disattiva un link all'anteprima. | ## Pubblicazione e domini Queste operazioni modificano ciò che vedono i visitatori. Chiedi prima al proprietario. | Strumento | Ambito | Funzione | | ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `review_publish` | `sites:read` | Mostra cosa verrebbe pubblicato, cosa ne impedisce la pubblicazione e il valore `expected_generation`. | | `publish_site` | `sites:publish` | Pubblica una build. | | `rollback_site` | `sites:publish` | Ripristina la pubblicazione di una versione precedente. | | `unpublish_site` | `sites:publish` | Mette il sito offline. | | `delete_site` | `sites:publish` | Elimina definitivamente un sito. `confirm_name` deve corrispondere al nome o allo slug del sito; per un sito pubblicato serve `delete_published: true`. L'operazione non è reversibile. | | `list_publications` | `sites:read` | Legge la cronologia delle pubblicazioni. | | `get_site_analytics` | `sites:read` | Legge il numero di visitatori di un sito in un determinato periodo. | | `list_domains` | `sites:read` | Legge i domini e i record DNS ancora necessari per ciascuno. | | `add_domain`, `check_domain` | `domains:write` | Collega un dominio e ne verifica i record DNS. | | `remove_domain` | `domains:write` | Scollega un dominio. | | `set_main_domain` | `domains:write` | Reindirizza gli altri indirizzi a un unico dominio e avvia una nuova build. | Per pubblicare, ripristinare una versione precedente, mettere il sito offline e modificare i domini serve anche il ruolo di amministratore del workspace. L'importazione e l'esportazione binarie del progetto si effettuano tramite la [REST API](/docs/api/overview) o la [CLI](/docs/cli/commands); gli agenti MCP leggono e modificano invece i singoli file. ## Account | Strumento | Ambito | Funzione | | -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `get_account` | `account:read` | Legge il workspace, il piano e gli ambiti di questa credenziale. | | `get_credit_balance` | `account:read` | Legge il saldo dei crediti e tutti i crediti assegnati. | | `get_usage` | `usage:read` | Legge l'utilizzo dei crediti nel tempo. | | `list_skills` | none | Elenca le guide: come creare un sito, modificare i contenuti, cambiare il design, importare dati, correggere una build e pubblicare. Chiamalo prima di creare una build. | | `get_skill` | none | Legge per intero una guida in formato Markdown. | | `send_feedback` | none | Segnala problemi o mancanze nell'API, nella CLI o nel server MCP. | ## Modifiche sicure Per ogni file che modifichi, invia l'hash ottenuto da `read_file` come `expected_hash`. Se qualcuno ha modificato il file nel frattempo, l'intera modifica viene rifiutata con un errore `conflict` e non viene scritto nulla. Rileggi i file, applica le modifiche e riprova. `publish_site` usa il valore `expected_generation` restituito da `review_publish` e viene rifiutato se il sito è stato pubblicato nel frattempo.