Gelato

Servidor MCP de la plataforma de impresión bajo demanda Gelato

GitHub

Documentación

Servidor MCP de Gelato

Un servidor MCP (Protocolo de Contexto de Modelo) para integrarse con la API de impresión bajo demanda de Gelato. Este servidor proporciona herramientas y recursos para buscar pedidos, recuperar detalles de pedidos y explorar catálogos de productos.

Características

🔧 Herramientas

  • search_orders: Búsqueda avanzada de pedidos con múltiples filtros (estado, país, rango de fechas, etc.)
  • get_order_summary: Recuperar detalles específicos de un pedido
  • search_products: Buscar productos en catálogos con capacidades de filtrado
  • get_product: Obtener información detallada sobre un producto específico
  • get_product_prices: Obtener información de precios para productos
  • check_stock_availability: Verificar disponibilidad de stock en todas las regiones
  • list_shipment_methods: Obtener métodos de envío disponibles

📚 Recursos

  • orders://{order_id}: Obtener información detallada del pedido
  • orders://recent: Obtener los 10 pedidos más recientes
  • orders://drafts: Obtener todos los pedidos en borrador
  • catalogs://list: Listar todos los catálogos de productos disponibles
  • catalogs://{catalog_uid}: Obtener información detallada del catálogo
  • catalogs://summary: Resumen rápido de todos los catálogos

Requisitos previos

Instalación

Instalación rápida con Claude Desktop

La forma más sencilla de añadir este servidor a Claude Desktop:

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

Reemplaza your_gelato_api_key_here con tu clave API real de Gelato del Portal de API de Gelato.

Alternativa: Puedes instalar sin la clave API y configurarla más tarde:

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

Luego usa la herramienta configure_gelato dentro de Claude para configurar tu clave API.

Instalación manual

Opción 1: Instalar desde 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

Opción 2: Instalar desde 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

Opción 3: Desarrollo local

  1. Clona este repositorio:

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

  2. Instala las dependencias:

    uv install
# or
pip install -e .

  3. Configura tu clave API:

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

Configuración

Crea un archivo .env en la raíz del proyecto con tu clave API de 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

Ejecutar el servidor

Después de la instalación mediante uvx:

# Run the server directly
mcp-server-gelato

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

Desarrollo 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"

Usar las herramientas y recursos

Buscar 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)

Obtener detalles del pedido

Usa el formato de URI de recurso para cargar el contexto del pedido:

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

O usa la herramienta:

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

Explorar catálogos de productos

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

Filtros de búsqueda disponibles

La herramienta search_orders admite filtrado extenso:

  • order_types: ["order", "draft"] - Filtrar por tipo de pedido
  • countries: ["US", "DE", "CA"] - Filtrar por país de envío
  • currencies: ["USD", "EUR", "GBP"] - Filtrar por moneda
  • financial_statuses: Estados de pago ("draft", "paid", "canceled", etc.)
  • fulfillment_statuses: Estados de cumplimiento ("created", "printed", "shipped", etc.)
  • search_text: Buscar en nombres de clientes e ID de referencia de pedidos
  • start_date/end_date: Filtrado por rango de fechas (formato ISO 8601)
  • channels: ["api", "shopify", "etsy", "ui"] - Filtrar por canal de pedido
  • limit/offset: Control de paginación (máximo 100 resultados por solicitud)

Características clave de diseño

  • Seguridad de tipos: Modelos Pydantic completos para todas las interacciones con la API
  • Manejo de errores: Manejo integral de errores con excepciones personalizadas
  • Soporte asíncrono: Todas las llamadas a la API son asíncronas para mejor rendimiento
  • Recursos vs. Herramientas: Separación clara entre exposición de datos (recursos) y operaciones (herramientas)
  • Extensible: Fácil de añadir nuevos endpoints siguiendo patrones establecidos

Manejo de errores

El servidor incluye manejo robusto de errores para escenarios comunes:

  • Errores de autenticación: Claves API inválidas o faltantes
  • Límite de velocidad: Reintento automático con retroceso exponencial
  • Errores de red: Manejo de tiempos de espera y errores de conexión
  • Errores de API: Manejo adecuado de respuestas de error de la API de Gelato
  • Errores de validación: Validación de datos de solicitud/respuesta

Solución de problemas

Error "No se pudo reconectar a gelato"

Este error ocurre cuando el servidor se inicia sin un GELATO_API_KEY válido. Aquí están las soluciones:

Para instalación con 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 desarrollo 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

Obtener tu clave API

  1. Visita el Portal de API de Gelato
  2. Regístrate o inicia sesión en tu cuenta
  3. Genera una clave API desde tu panel de control
  4. Usa la clave en el comando de instalación o variable de entorno

Problemas comunes

  • Clave API inválida: Verifica que tu clave API sea correcta y esté activa
  • Problemas de red: Asegura la conectividad a internet y que no haya firewall bloqueando
  • Problemas de permisos: Asegúrate de que tu clave API tenga los permisos necesarios

Desarrollo

Añadir nuevas características

  1. Nuevas herramientas: Añade a src/tools/ y regístralas en el servidor
  2. Nuevos recursos: Añade a src/resources/ y regístralos en el servidor
  3. Nuevos modelos: Añade a src/models/ con validación Pydantic adecuada
  4. Nuevos endpoints de API: Extiende GelatoClient en src/client/

Pruebas

# 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())
"

Solución de problemas

Problemas comunes

  1. Error de clave API: Asegúrate de que GELATO_API_KEY esté configurado correctamente en tu entorno
  2. Tiempo de espera de conexión: Verifica tu conexión de red y aumenta el tiempo de espera en la configuración
  3. Límite de velocidad: El servidor reintenta automáticamente con retroceso, pero puede que necesites ralentizar las solicitudes

Modo de depuración

Habilita el registro de depuración:

DEBUG=true python main.py

Contribuciones

  1. Sigue la estructura y los patrones de código existentes
  2. Añade manejo de errores adecuado para nuevos endpoints
  3. Incluye modelos Pydantic para validación de datos
  4. Documenta nuevas características en este README

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Soporte

Para problemas con la API de Gelato, visita el Centro de ayuda de Gelato. Para problemas relacionados con MCP, consulta la documentación de MCP.