Gelato

Servidor MCP de Automação Gelato API e Shopify

Um servidor Model Context Protocol (MCP) para integração com a API Gelato Print-on-Demand. Este servidor permite que agentes de IA (como Antigravity, Claude, ChatGPT, etc.) automatizem a criação de produtos a partir de URLs/arquivos de design personalizados, inspecionem modelos de produtos, gerenciem conexões de lojas Shopify, explorem especificações de catálogo e processem pedidos de fulfillment de impressão.

---

✨ Principais Recursos

• 🎨 Criação de Produtos Baseada em Modelos: Envie programaticamente arquivos de design (PNG, JPG, PDF) para os placeholders de modelos de produtos Gelato (ImageFront, ImageBack, etc.) e publique itens personalizados de print-on-demand diretamente em suas lojas de e-commerce conectadas (Shopify, WooCommerce, etc.).
• 🏪 Gerenciamento de Múltiplas Lojas: Inspecione lojas conectadas (gelato_list_stores), visualize produtos da loja (gelato_list_products), inspecione o status do produto (gelato_get_product) e exclua produtos (gelato_delete_product).
• 📐 Inspeção de Modelos: Liste modelos (gelato_list_templates) e inspecione estruturas de camadas e IDs de variantes (gelato_get_template).
• 📚 Exploração de Catálogo: Pesquise o catálogo global de produtos da Gelato (gelato_search_catalog_products), liste categorias (gelato_list_catalogs) e obtenha especificações de produtos (gelato_get_catalog_product).
• 📦 Fulfillment de Pedidos e Cotações: Solicite cotações de preços de envio/impressão (gelato_quote_order), faça pedidos de impressão (gelato_create_order), acompanhe o status do pedido (gelato_get_order) e pesquise pedidos (gelato_search_orders).

---

🛠️ Ferramentas MCP Disponíveis

1. Gerenciamento de Lojas e Produtos

• gelato_list_stores — Liste todas as lojas conectadas e seus storeIds.
• gelato_create_product_from_template — Crie e publique um novo produto em uma loja a partir de um modelo Gelato com URLs de design personalizadas, títulos, descrições, tags e variantes.
• gelato_list_products — Liste todos os produtos publicados em uma loja específica.
• gelato_get_product — Recupere informações detalhadas e status de publicação (publishing, active, publishing_error) de um produto.
• gelato_delete_product — Remova um produto de uma loja.

2. Modelos Gelato

• gelato_list_templates — Liste todos os modelos de produtos criados na sua conta Gelato.
• gelato_get_template — Recupere detalhes de um modelo específico, incluindo nomes de placeholders de camadas de imagem (ImageFront, ImageBack) e templateVariantIds.

3. Catálogo de Produtos

• gelato_list_catalogs — Liste as principais categorias do catálogo de produtos (Vestuário, Arte de Parede, Canecas, Cartões, etc.).
• gelato_search_catalog_products — Pesquise itens do catálogo usando filtros de atributos.
• gelato_get_catalog_product — Obtenha especificações, áreas imprimíveis, dimensões disponíveis, opções e preços para um UID de produto do catálogo.

4. Pedidos e Cotações

• gelato_create_order — Envie um pedido de fulfillment de impressão para a Gelato.
• gelato_quote_order — Calcule opções de envio e cotações de custo antes de fazer um pedido.
• gelato_get_order — Recupere o status atual do pedido e detalhes de rastreamento.
• gelato_search_orders — Pesquise pedidos com paginação e busca por texto.

---

⚙️ Instalação e Configuração

Pré-requisitos

• Node.js 18.x ou superior
• Chave da API Gelato (obtenível no Painel Gelato → Desenvolvedor > Chaves de API)

Instalação

git clone https://github.com/altetsa/gelato-mcp-server.git
cd gelato-mcp-server
npm install

Configuração

Adicione a entrada do servidor ao seu arquivo de configuração MCP (por exemplo, mcp_config.json ou Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "gelato": {
      "command": "node",
      "args": [
        "/path/to/gelato-mcp-server/index.js"
      ],
      "env": {
        "GELATO_API_KEY": "your_gelato_api_key_here"
      }
    }
  }
}

---

🚀 Fluxo de Trabalho de Criação de Produto

1. Obtenha o ID da Loja: Chame gelato_list_stores para obter o storeId da sua loja de destino.
2. Inspecione o Modelo: Chame gelato_get_template com seu templateId para verificar os nomes dos placeholders de camadas (por exemplo, ImageFront) e templateVariantIds.
3. Crie o Produto: Chame gelato_create_product_from_template com:
   • storeId
   • templateId
   • title e description
   • variants: Array de objetos contendo templateVariantId e imagePlaceholders com name e fileUrl público do seu design de impressão.

Exemplo de Payload de Chamada de Ferramenta:

{
  "storeId": "82ceff8e-c559-45da-9c93-3982702a0906",
  "templateId": "c12a363e-0d4e-4d96-be4b-bf4138eb8743",
  "title": "Custom Printed T-Shirt",
  "description": "<p>High quality custom printed unisex crewneck t-shirt.</p>",
  "isVisibleInTheOnlineStore": true,
  "tags": ["t-shirt", "custom-print", "unisex"],
  "salesChannels": ["web"],
  "variants": [
    {
      "templateVariantId": "83e30e31-0aee-4eca-8a8f-dceb2455cdc1",
      "imagePlaceholders": [
        {
          "name": "ImageFront",
          "fileUrl": "https://example.com/designs/front_artwork.png"
        }
      ]
    }
  ]
}

---

📄 Licença

MIT © altetsa