O MCP (Model Context Protocol) da Nuvemshop conecta um agente de IA à CLI da Nuvemshop. Com essa conexão, você descreve em linguagem natural a alteração que quer no tema de uma loja, como incluir uma seção nova na home, e o agente identifica os arquivos envolvidos, aplica a mudança e devolve um link de pré-visualização.
Helpjuice Success Callout Title
Essa funcionalidade está sendo liberado de forma gradual e ainda não está disponível para todas as contas. O recurso é voltado a quem trabalha com código de tema, como parceiros, agências e pessoas desenvolvedoras.
Requisitos
O MCP já vem incluído na CLI da Nuvemshop, por isso não existe instalação separada. Para usá-lo, confira se você tem:
- A CLI da Nuvemshop instalada e autenticada na loja, com o token de acesso configurado na pasta local do tema.
- A pasta local da loja em que você vai trabalhar.
- Um agente de IA compatível com MCP, como o Claude.
Como é feita a conexão?
A conexão é feita a partir da pasta local da loja, e vale uma por pasta. Para conectar, siga os passos abaixo:
1. Abrir o terminal na pasta local da loja em que você vai trabalhar.
2. Executar o comando "nuvemshop mcp serve".
3. Adicionar esse MCP ao agente de IA que você usa.
4. Pedir ao agente a lista de temas da loja, para confirmar que a conexão está funcionando.
Pronto!
O agente responde com os temas da loja e informa, para cada um, o tipo, o tema base e qual está em produção. Esse retorno confirma que o MCP está habilitado e que a autenticação da pasta está válida.
Como pedir uma alteração no tema da loja?
O pedido pode descrever o objetivo em vez do caminho técnico, porque o agente consulta a estrutura do tema antes de propor a mudança.
Para ver a referência completa dos comandos e dos parâmetros de cada um, consulte a documentação oficial do CLI.
No passo a passo abaixo te mostramos um exemplo de como fazer uma modificação usando a inteligência artificial:
1. Descrever a alteração ao agente, indicando que ele deve trabalhar sobre uma cópia. O exemplo que vamos utilizar é de copiar o tema em produção e adicionar uma seção de boas-vindas na home.
2. Autorizar a criação do clone do tema, quando o agente solicitar.
Helpjuice Warning Callout Title
Cada ação que escreve na loja passa pela sua autorização, o que mantém o tema em produção intacto até você decidir publicar.
3. Autorizar o pull dos arquivos do tema para a pasta local.
4. Revisar a alteração proposta pelo agente, que indica os arquivos a modificar e onde a seção nova entra na ordenação da home nesse caso.
5. Conferir o resultado da validação da estrutura do arquivo e o diff que o agente apresenta antes do envio.
6. Autorizar o push das alterações para o clone.
7. Abrir o link de pré-visualização que o agente devolve, no formato "?theme_installation_id=" seguido do identificador do clone.
Pronto!
A alteração aparece no clone, identificado como rascunho, e a loja em produção permanece como estava. Se você não especificar textos no pedido, o agente preenche a seção com um conteúdo genérico, que você ajusta depois.
Helpjuice Info Callout Title
A primeira abertura do link de pré-visualização demora mais que as seguintes, porque o clone está sendo carregado pela primeira vez. Vale aguardar o carregamento antes de concluir que a alteração não foi aplicada.
Como publicar ou descartar o clone do tema?
O MCP não publica nada por conta própria. A publicação acontece somente quando você pede de forma explícita, e o clone fica como rascunho até então.
Para publicar, peça ao agente que publique o clone e informe o identificador do tema quando ele solicitar. Para descartar, peça a exclusão do clone e informe o identificador da mesma forma. Depois da exclusão, pedir a lista de temas novamente confirma que o clone não está mais lá.
Helpjuice Success Callout Title
Publicar um clone substitui o tema que está no ar e descarta o que tenha sido editado no editor da loja depois da criação do clone. Antes de publicar, confirme com o cliente que ninguém está editando o tema ao vivo, principalmente quando o clone foi criado há muitas horas.
Quando você trabalha direto na pasta do tema publicado, em vez de um clone, o push atinge o tema em produção e a alteração fica visível na loja assim que o envio termina. Nesse caso a revisão precisa acontecer no diff, antes de autorizar o push, porque não existe etapa de pré-visualização.
Perguntas frequentes
Quais ações pedem a minha autorização?
O MCP separa as ações por nível de impacto na loja. As de leitura acontecem direto, e as que escrevem exigem um passo de confirmação seu:
Tipo de ação |
Exemplos |
O que o MCP exige |
|---|---|---|
| Leitura | Listar os temas da loja, ler os arquivos do tema | Nenhuma confirmação |
| Escrita | Clonar um tema, fazer pull, fazer push | Aceite explícito a cada ação |
| Destrutiva ou definitiva | Excluir uma instalação de tema, publicar um tema | Aceite explícito e digitação do identificador do tema |
A digitação do identificador existe para que a exclusão e a publicação não aconteçam por um aceite automático. É a diferença entre confirmar uma ação e confirmar exatamente sobre qual tema ela vai acontecer.
O texto criado pelo terminal é editável no painel administrador?
Depende de como a seção foi construída, e vale definir isso no próprio pedido ao agente.
Quando a seção nasce como um bloco em um arquivo de página, o título e o texto ficam disponíveis no editor de temas, e o lojista altera o conteúdo sem depender de código. Quando o texto é escrito direto no template, o conteúdo fica fixo e só muda por código.
Para tornar editável uma seção que nasceu com texto fixo, o caminho é declarar as configurações correspondentes em "config/settings.txt" e substituir o texto do template por essas configurações. Esse ajuste também pode ser pedido ao agente.
Se a seção usa imagem e nenhuma imagem foi configurada, o tema exibe uma imagem de placeholder até que a definitiva seja enviada pelo editor.