Servidor MCP multi-tienda de Shopify de Hey Harper

Un pequeño servidor MCP remoto que guarda los tokens permanentes de la API de Admin de Shopify de las cinco tiendas de Hey Harper y obtiene pedidos sin cumplir / candidatos que requieren atención en todas las tiendas con una sola conexión — sin switch-shop, sin re-autorización OAuth por tienda. Esto es lo que hace que el informe diario de «pedidos que requieren atención» sea ejecutable sin supervisión.

Por qué existe

El conector oficial de Shopify mantiene una tienda a la vez y obliga a una re-autorización OAuth en cada cambio de tienda — imposible de automatizar para un trabajo programado. Este servidor lo evita por completo usando tokens de la API de Admin de aplicaciones personalizadas (permanentes, sin OAuth) y consultando todas las tiendas directamente.

Related MCP server: Shopify MCP

Herramientas que expone

Devuelve cada pedido normalizado y enriquecido (released_hold_at analizado, indicadores de etiqueta de Everstox, oos por línea) pero deliberadamente no decide si «requiere atención» — el umbral de retraso en días hábiles, la regla OOS (solo EU/UK/BR/MX) y las exclusiones de Everstox permanecen en tu tarea de Cowork para que puedas ajustar umbrales y añadir calendarios de festivos sin volver a desplegar.

Configuración — paso a paso

1. Crea una aplicación personalizada + token en CADA tienda

En el administrador de cada tienda de Hey Harper (US, EU, UK, BR, MX):

1. Configuración → Aplicaciones y canales de venta → Desarrollar aplicaciones → Crear una aplicación (nómbrala, p. ej., cowork-unfulfilled-reader).

2. Configura los scopes de la API de Admin y habilita (solo lectura es suficiente):

   • read_orders

   • read_all_orders (permite consultar pedidos de más de 60 días)

   • read_products

   • read_inventory

   • read_fulfillments

   • read_merchant_managed_fulfillment_orders

3. Instala la aplicación, luego bajo Credenciales de API revela el token de acceso de la API de Admin (shpat_…). Cópialo.

4. Anota el dominio myshopify de la tienda (p. ej., hey-harper-shop-uk.myshopify.com).

Terminarás con cinco pares (dominio, token). Nunca los subas a un repositorio ni los pegues en un chat — van directamente al almacén de secretos del host en el paso 3.

2. Despliega el servidor

El repositorio incluye un Dockerfile, así que cualquier host de contenedores sirve (Render, Railway, Fly.io, un VPS). Debe tener acceso normal a internet y una URL HTTPS pública.

Render (ejemplo, el más sencillo):

• Nuevo → Web Service → conecta este repositorio (o «Despliega desde un Dockerfile»).

• Render detecta automáticamente el Dockerfile. No se necesita ningún comando de compilación/inicio.

• Proporciona HTTPS + una URL pública automáticamente.

Fly.io / Railway: apúntalos al Dockerfile de la misma manera.

Prueba local:

npm install
npm run build
MCP_AUTH_TOKEN=$(openssl rand -hex 32) HH_UK_DOMAIN=hey-harper-shop-uk.myshopify.com HH_UK_TOKEN=shpat_xxx npm start
# health check:
curl localhost:3000/health

3. Configura los secretos de entorno en el host

Copia .env.example como referencia y configura estos en la interfaz de entorno/secretos de tu host:

• MCP_AUTH_TOKEN — una cadena aleatoria larga (openssl rand -hex 32). Configúralo — es el token de portador que protege tu endpoint.

• HH_US_DOMAIN / HH_US_TOKEN, HH_EU_*, HH_UK_*, HH_BR_*, HH_MX_* — los pares del paso 1.

Una tienda solo entra en funcionamiento cuando ambos su dominio y su token están configurados, así que puedes empezar con UK y añadir el resto a medida que generes tokens.

4. Añádelo a Claude como conector personalizado

En claude.ai → Configuración → Conectores → Añadir conector personalizado:

• URL: https://<tu-host>/mcp

• Autenticación: proporciona el token de portador (MCP_AUTH_TOKEN) para que las solicitudes envíen Authorization: Bearer <token>.

Si la interfaz del conector no puede adjuntar una cabecera estática en tu plan, una alternativa es configurar MCP_PATH en una ruta imposible de adivinar (p. ej. /mcp/9f3c…) y usar esa como URL — la ruta secreta actúa entonces como credencial. El token de portador es preferible donde se admita.

Una vez conectado, heyharper_list_stores, heyharper_pull_store_orders y heyharper_pull_all_stores aparecen como herramientas.

5. Conecta el informe diario

Apunta tu tarea diaria de Cowork de las 9 a. m. a heyharper_pull_all_stores, luego aplica la lógica de clasificación (mantenida en la tarea, según la especificación de traspaso):

clock    = releasedHoldAt if hasReleasedHold else processedAt
late     = business_days_since(clock) >= 2      (weekends excluded, warehouse TZ)
shop_oos = anyLineOos                            (only where storeAppliesOos)
excluded = hasOosEverstox OR (hasHoldEverstox AND NOT hasReleasedHold)
           OR (hasSetOnHold AND NOT hasReleasedHold)
needs_attention = (late OR shop_oos) AND NOT excluded

Publica el resumen en #daily-unfulfilled.

Notas de seguridad

• Los tokens viven solo en el entorno/secretos del host — nunca en el repositorio (.env está en gitignore).

• Configura siempre MCP_AUTH_TOKEN antes de exponer la URL públicamente; el servidor registra una advertencia si falta.

• Todas las herramientas son de solo lectura (solo scopes read_*) — el servidor no puede modificar tus tiendas.

Variables de entorno