Ferramentas
As ferramentas que um agente pode chamar para criar, alterar e publicar um site, e o escopo necessário para cada uma.
A cobertura de operações gerada mapeia REST, CLI e MCP.
Para descobrir as operações, leia atelier201://operations e, em seguida,
atelier201://operations/{operation_id} para consultar o contrato completo de uma operação. O documento completo
é atelier201://openapi. Argumentos desconhecidos são rejeitados, em vez de serem
ignorados silenciosamente.
get_workspace lê os arquivos não confirmados e as diferenças sem executar bash. Ele
usa a mesma permissão sites:write do endpoint REST do workspace e não altera
nem o rascunho nem o site publicado.
As ferramentas são estruturadas em torno do trabalho feito por um agente, não dos endpoints. Suas descrições são escritas manualmente, porque um modelo as lê como sua interface completa: cada descrição informa o que a ferramenta altera, se isso fica visível para os visitantes e o que chamar em seguida.
Só são oferecidas as ferramentas permitidas pelos escopos da sua credencial, então uma conexão
sem sites:publish nunca verá publish_site. Uma ferramenta consome créditos:
generate_media, e somente com a permissão media:generate.
Ordem de trabalho
get_accounte, em seguida,list_sitespara obter umsite_id, oucreate_site.- Use
edit_textpara qualquer texto visível,set_fieldpara um campo conhecido,save_entryesave_entriespara entradas, esave_singleton themepara a aparência. Useread_fileeedit_files(oubashe depoiscommit_workspace) somente para alterar o código. - Cada salvamento inicia uma compilação e retorna
build:get_buildcom esse ID aguarda (50 s por padrão) e responde quando o status éreadyoufailed. Compreview: true, uma compilação pronta vem acompanhada de um link para abrir; sem navegador,read_pagelê as páginas.build_siteserve para compilar uma revisão específica ou tentar novamente. show_site: em um host que exibe apps (Claude, ChatGPT), o proprietário vê o rascunho ao vivo em um cartão, com a opção Publish. Em outros ambientes, useshare_previewe envie o link.review_publishe, depois que o proprietário aprovar,publish_site.
Sites e conteúdo
| Ferramenta | Escopo | O que faz |
|---|---|---|
list_sites, get_site | sites:read | Lê os sites do workspace. |
create_site | sites:write | Cria um site a partir do modelo inicial e inicia a primeira compilação. |
rename_site | sites:write | Altera o nome exibido no Atelier201. |
get_content_model | sites:read | Lê coleções e elementos únicos com seus esquemas JSON. |
list_entries, get_entry | sites:read | Lê as entradas de uma coleção. |
save_entry | sites:write | Grava uma entrada, após validá-la. Uma nova entrada começa como rascunho. |
delete_entry | sites:write | Remove uma entrada do rascunho. |
get_singleton | sites:read | Lê os dados comerciais, o tema ou a navegação. |
save_singleton | sites:write | Substitui um elemento único inteiro, após validá-lo. |
set_field | sites:write | Altera um campo pelo endereço data-atelier201-field. |
apply_site_plan | sites:write | Grava uma primeira versão ou uma reformulação ampla em uma única chamada: dados comerciais, tema, navegação, entradas e imagens, tudo validado em conjunto. |
place_image | sites:write | Coloca uma imagem em um campo de imagem (uma descrição para buscar imagens de banco, um resultado escolhido ou um arquivo do site), com seu texto alternativo, em uma única chamada. |
edit_text | sites:write | Altera um texto onde quer que apareça (no conteúdo ou no código), conforme ele é exibido na página. |
Arquivos, histórico e conjuntos de alterações
| Ferramenta | Escopo | O que faz |
|---|---|---|
list_files, read_file, read_files, search_files | sites:read | Lê o projeto. read_file retorna o hash a ser enviado como expected_hash; read_files lê até 30 arquivos em uma chamada. |
edit_files | sites:write | Aplica operações de inclusão, exclusão e movimentação como uma única entrada no histórico. |
get_workspace | sites:write | Lê os arquivos não confirmados e suas diferenças sem executar um comando. |
open_changeset, stage_changes, commit_changeset, abandon_changeset | sites:write | Cria uma entrada no histórico a partir de várias chamadas. |
list_history, compare_revisions | sites:read | Lê o histórico. |
restore_revision | sites:write | Faz o rascunho corresponder a uma revisão anterior, como uma nova entrada. |
Mídia
| Ferramenta | Escopo | O que faz |
|---|---|---|
list_media | sites:read | Lê os arquivos enviados e o espaço de armazenamento restante. |
upload_media | sites:write | Envia um arquivo em base64, com no máximo 5 MB pelo MCP. |
delete_media | sites:write | Remove um arquivo das próximas compilações. |
search_stock_media | sites:read | Pesquisa fotos e vídeos de bancos gratuitos (Pixabay). |
import_stock_media | sites:write | Copia um resultado para a mídia do site, com os créditos correspondentes. |
list_media_models | sites:read | Lista os modelos de IA para imagens e vídeos e seus preços em créditos. |
generate_media | media:generate | Cria uma imagem ou um vídeo com IA. Consome créditos: use estimate_only primeiro e, em seguida, max_credits. |
get_media_generation | sites:read | Informa o andamento de uma geração e o arquivo quando estiver pronto. |
Compilação e pré-visualização
| Ferramenta | Escopo | O que faz |
|---|---|---|
build_site | sites:write | Compila o rascunho. Retorna imediatamente uma compilação com status queued. |
list_builds, get_build, get_build_log | sites:read | Lê as compilações e o registro de uma compilação com falha. get_build aceita wait (responde quando a compilação termina) e preview (um link para uma compilação pronta; requer sites:write). |
read_page | sites:read | Lê uma página da compilação como um visitante a veria, incluindo os problemas que uma revisão rápida detectaria: para agentes sem navegador. |
show_site | sites:read | Abre o cartão do site, um app MCP: o rascunho ao vivo (recarrega automaticamente após cada compilação), uma imagem da página inicial quando o host não consegue exibi-la em um frame, o botão Publish (Go live, Publish changes) e Comment, que envia à conversa o pedido “change this” sobre um elemento. Sem sites:write, o cartão mostra apenas a imagem. |
share_preview | sites:write | Cria um link privado para uma compilação, válido por 7 dias por padrão. |
list_previews | sites:read | Lê os links de pré-visualização. |
revoke_preview | sites:write | Desativa um link de pré-visualização. |
Publicação e domínios
Estas ações alteram o que os visitantes veem. Consulte o proprietário primeiro.
| Ferramenta | Escopo | O que faz |
|---|---|---|
review_publish | sites:read | Mostra o que será publicado, o que impede a publicação e o expected_generation. |
publish_site | sites:publish | Publica uma compilação. |
rollback_site | sites:publish | Volta a disponibilizar uma publicação anterior. |
unpublish_site | sites:publish | Tira o site do ar. |
delete_site | sites:publish | Exclui um site permanentemente. confirm_name deve ser o nome ou o slug do site; para excluir um site publicado, é necessário delete_published: true. Não é possível desfazer. |
list_publications | sites:read | Lê o histórico de publicações. |
get_site_analytics | sites:read | Lê o número de visitantes de um site ao longo de um período. |
list_domains | sites:read | Lê os domínios e os registros DNS que ainda são necessários para cada um. |
add_domain, check_domain | domains:write | Conecta um domínio e verifica seus registros DNS. |
remove_domain | domains:write | Desconecta um domínio. |
set_main_domain | domains:write | Redireciona os outros endereços para um único domínio e inicia uma nova compilação. |
Publicar, reverter uma publicação, tirar um site do ar e alterar domínios também exigem um administrador do workspace. A importação e exportação de projetos binários são feitas pela API REST ou pela CLI; agentes MCP leem e alteram arquivos individuais.
Conta
| Ferramenta | Escopo | O que faz |
|---|---|---|
get_account | account:read | Lê o workspace, o plano e os escopos desta credencial. |
get_credit_balance | account:read | Lê o saldo de créditos e cada concessão. |
get_usage | usage:read | Lê o uso de créditos ao longo do tempo. |
list_skills | none | Lista os manuais: como criar um site, editar conteúdo, alterar o design, importar dados, corrigir uma compilação e publicar. Chame antes de criar o site. |
get_skill | none | Lê um manual completo em Markdown. |
send_feedback | none | Relata algo incorreto ou ausente na API, na CLI ou no servidor MCP. |
Como escrever com segurança
Envie o hash de read_file como expected_hash em cada arquivo alterado. Se
alguém o tiver alterado nesse meio-tempo, a alteração inteira será recusada com um erro conflict,
e nada será gravado. Leia os arquivos novamente, aplique sua alteração sobre a versão atual e tente de novo.
publish_site recebe o expected_generation de review_publish e é
recusado se o site tiver sido publicado nesse meio-tempo.