Strumenti
Gli strumenti che un agente può usare per creare, modificare e pubblicare un sito, e le autorizzazioni necessarie per ciascuno.
La copertura delle operazioni generate 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
get_account, poilist_sitesper ottenere unsite_id, oppurecreate_site.edit_textper qualsiasi testo visibile,set_fieldper un campo già individuato,save_entryesave_entriesper le voci,save_singleton themeper l’aspetto. Usaread_fileeedit_files(oppurebashe poicommit_workspace) solo per modificare il codice.- Ogni salvataggio avvia una build e restituisce
build:get_buildcon quell’ID attende (50 s per impostazione predefinita) e risponde quando lo stato èreadyofailed. Conpreview: true, una build pronta include un link da aprire; se non hai un browser,read_pagelegge le pagine.build_siteserve per creare una build di una determinata revisione o riprovare. 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, usashare_previewe inviagli il link.review_publish, poipublish_sitesolo 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 o la CLI; 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.