Gelato

Servidor MCP da plataforma de impressão sob demanda Gelato

GitHub

Documentação

Servidor MCP Gelato

Um servidor MCP (Model Context Protocol) para integração com a API de print-on-demand da Gelato. Este servidor fornece ferramentas e recursos para pesquisar pedidos, recuperar detalhes de pedidos e explorar catálogos de produtos.

Recursos

🔧 Ferramentas

  • search_orders: Pesquisa avançada de pedidos com múltiplos filtros (status, país, intervalo de datas, etc.)
  • get_order_summary: Recupera detalhes específicos de pedidos
  • search_products: Pesquisa produtos em catálogos com capacidades de filtragem
  • get_product: Obtém informações detalhadas sobre um produto específico
  • get_product_prices: Obtém informações de preços para produtos
  • check_stock_availability: Verifica disponibilidade de estoque em várias regiões
  • list_shipment_methods: Obtém métodos de envio disponíveis

📚 Recursos

  • orders://{order_id}: Obtém informações detalhadas do pedido
  • orders://recent: Obtém os 10 pedidos mais recentes
  • orders://drafts: Obtém todos os pedidos de rascunho
  • catalogs://list: Lista todos os catálogos de produtos disponíveis
  • catalogs://{catalog_uid}: Obtém informações detalhadas do catálogo
  • catalogs://summary: Visão geral rápida de todos os catálogos

Pré-requisitos

Instalação

Instalação Rápida com Claude Desktop

A maneira mais fácil de adicionar este servidor ao Claude Desktop:

claude mcp add gelato --env GELATO_API_KEY="your_gelato_api_key_here" -- uvx mcp-server-gelato

Substitua your_gelato_api_key_here pela sua chave de API real da Gelato do Portal de API da Gelato.

Alternativa: Você pode instalar sem a chave de API e configurá-la depois:

claude mcp add gelato -- uvx mcp-server-gelato

Em seguida, use a ferramenta configure_gelato dentro do Claude para configurar sua chave de API.

Instalação Manual

Opção 1: Instalar do PyPI (Recomendado)

# Install the package
uv install mcp-server-gelato
# or
pip install mcp-server-gelato

# Run the server
GELATO_API_KEY="your_api_key_here" uvx mcp-server-gelato

# Or install as a tool
uv tool install mcp-server-gelato
GELATO_API_KEY="your_api_key_here" mcp-server-gelato

Opção 2: Instalar do GitHub

# Install directly from GitHub
uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato

# Or use uv tool install
uv tool install git+https://github.com/madzarmaksim/mcp-server-gelato

Opção 3: Desenvolvimento Local

  1. Clone este repositório:

    git clone https://github.com/madzarmaksim/mcp-server-gelato.git
cd mcp-server-gelato

  2. Instale as dependências:

    uv install
# or
pip install -e .

  3. Configure sua chave de API:

    cp .env.example .env
# Edit .env and add your GELATO_API_KEY

Configuração

Crie um arquivo .env na raiz do projeto com sua chave de API da Gelato:

GELATO_API_KEY=your_gelato_api_key_here

# Optional configuration
# GELATO_BASE_URL=https://order.gelatoapis.com
# GELATO_PRODUCT_URL=https://product.gelatoapis.com
# TIMEOUT=30
# MAX_RETRIES=3
# DEBUG=false

Uso

Executando o Servidor

Após instalação via uvx:

# Run the server directly
mcp-server-gelato

# Or with environment variables
GELATO_API_KEY=your_key_here mcp-server-gelato

Desenvolvimento local:

# Direct execution
python main.py

# Development mode with inspector
uv run mcp dev main.py

# Install in Claude Desktop from local directory
uv run mcp install . --name "Gelato API"

Usando as Ferramentas e Recursos

Pesquisar Pedidos

# Search for draft orders
search_orders(order_types=["draft"])

# Search US orders from last month
search_orders(
    countries=["US"], 
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-31T23:59:59Z"
)

# Search by customer name
search_orders(search_text="John Smith", limit=10)

Obter Detalhes do Pedido

Use o formato de URI do recurso para carregar o contexto do pedido:

orders://37365096-6628-4538-a9c2-fbf9892deb85

Ou use a ferramenta:

get_order_summary(order_id="37365096-6628-4538-a9c2-fbf9892deb85")

Explorar Catálogos de Produtos

catalogs://list          # List all catalogs
catalogs://posters       # Get poster catalog details
catalogs://summary       # Quick overview

Filtros de Pesquisa Disponíveis

A ferramenta search_orders suporta filtragem extensiva:

  • order_types: ["order", "draft"] - Filtrar por tipo de pedido
  • countries: ["US", "DE", "CA"] - Filtrar por país de envio
  • currencies: ["USD", "EUR", "GBP"] - Filtrar por moeda
  • financial_statuses: Status de pagamento ("draft", "paid", "canceled", etc.)
  • fulfillment_statuses: Status de atendimento ("created", "printed", "shipped", etc.)
  • search_text: Pesquisar em nomes de clientes e IDs de referência de pedidos
  • start_date/end_date: Filtragem por intervalo de datas (formato ISO 8601)
  • channels: ["api", "shopify", "etsy", "ui"] - Filtrar por canal de pedido
  • limit/offset: Controle de paginação (máximo de 100 resultados por solicitação)

Principais Características de Design

  • Segurança de Tipos: Modelos Pydantic completos para todas as interações com a API
  • Tratamento de Erros: Tratamento abrangente de erros com exceções personalizadas
  • Suporte Assíncrono: Todas as chamadas de API são assíncronas para melhor desempenho
  • Recursos vs Ferramentas: Separação clara entre exposição de dados (recursos) e operações (ferramentas)
  • Extensível: Fácil adicionar novos endpoints seguindo padrões estabelecidos

Tratamento de Erros

O servidor inclui tratamento robusto de erros para cenários comuns:

  • Erros de autenticação: Chaves de API inválidas ou ausentes
  • Limitação de taxa: Tentativa automática com backoff exponencial
  • Erros de rede: Tratamento de timeout e erros de conexão
  • Erros de API: Tratamento adequado das respostas de erro da API da Gelato
  • Erros de validação: Validação de dados de solicitação/resposta

Solução de Problemas

Erro "Falha ao reconectar ao gelato"

Este erro ocorre quando o servidor inicia sem um GELATO_API_KEY válido. Aqui estão as soluções:

Para Instalação com Claude Desktop:

# Install with API key (recommended)
claude mcp add gelato --env GELATO_API_KEY="your_actual_api_key" -- uvx mcp-server-gelato

# Or install without API key and configure later
claude mcp add gelato -- uvx mcp-server-gelato
# Then use the configure_gelato tool in Claude

Para Desenvolvimento Local:

# Using PyPI package
GELATO_API_KEY="your_api_key_here" uvx mcp-server-gelato

# Or using local code
export GELATO_API_KEY=your_api_key_here
python main.py

# Or create .env file for local development
echo "GELATO_API_KEY=your_api_key_here" > .env
python main.py

Obtendo Sua Chave de API

  1. Visite o Portal de API da Gelato
  2. Cadastre-se ou faça login na sua conta
  3. Gere uma chave de API no seu painel
  4. Use a chave no comando de instalação ou na variável de ambiente

Problemas Comuns

  • Chave de API Inválida: Verifique novamente se sua chave de API está correta e ativa
  • Problemas de Rede: Garanta conectividade com a internet e que nenhum firewall esteja bloqueando
  • Problemas de Permissão: Certifique-se de que sua chave de API tenha as permissões necessárias

Desenvolvimento

Adicionando Novos Recursos

  1. Novas Ferramentas: Adicione a src/tools/ e registre no servidor
  2. Novos Recursos: Adicione a src/resources/ e registre no servidor
  3. Novos Modelos: Adicione a src/models/ com validação Pydantic adequada
  4. Novos Endpoints de API: Estenda GelatoClient em src/client/

Testes

# Test connection with your API key
python -c "
import asyncio
from src.config import get_settings
from src.client.gelato_client import GelatoClient

async def test():
    settings = get_settings()
    async with GelatoClient(settings.gelato_api_key, settings) as client:
        catalogs = await client.list_catalogs()
        print(f'Found {len(catalogs)} catalogs')

asyncio.run(test())
"

Solução de Problemas

Problemas Comuns

  1. Erro de Chave de API: Certifique-se de que GELATO_API_KEY esteja configurado corretamente no seu ambiente
  2. Timeout de Conexão: Verifique sua conexão de rede e aumente o timeout na configuração
  3. Limitação de Taxa: O servidor tenta automaticamente com backoff, mas você pode precisar diminuir a velocidade das solicitações

Modo de Depuração

Ative o registro de depuração:

DEBUG=true python main.py

Contribuindo

  1. Siga a estrutura e os padrões de código existentes
  2. Adicione tratamento de erros adequado para novos endpoints
  3. Inclua modelos Pydantic para validação de dados
  4. Documente novos recursos neste README

Licença

Este projeto é licenciado sob a Licença MIT.

Suporte

Para problemas com a API da Gelato, visite a Central de Ajuda da Gelato. Para problemas relacionados ao MCP, consulte a documentação do MCP.