--- title: "Ferramentas" description: "As ferramentas que um agente pode chamar para criar, alterar e publicar um site, e o escopo necessário para cada uma." canonical: "https://atelier201.com/docs/pt/mcp/standard-tools" updated: "2026-11-06" --- # Ferramentas A [cobertura de operações gerada](/docs/api/surfaces) 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 1. `get_account` e, em seguida, `list_sites` para obter um `site_id`, ou `create_site`. 2. Use `edit_text` para qualquer texto visível, `set_field` para um campo conhecido, `save_entry` e `save_entries` para entradas, e `save_singleton theme` para a aparência. Use `read_file` e `edit_files` (ou `bash` e depois `commit_workspace`) somente para alterar o código. 3. Cada salvamento inicia uma compilação e retorna `build`: `get_build` com esse ID aguarda (50 s por padrão) e responde quando o status é `ready` ou `failed`. Com `preview: true`, uma compilação pronta vem acompanhada de um link para abrir; sem navegador, `read_page` lê as páginas. `build_site` serve para compilar uma revisão específica ou tentar novamente. 4. `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, use `share_preview` e envie o link. 5. `review_publish` e, 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](/docs/api/overview) ou pela [CLI](/docs/cli/commands); 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.