Servidor MCP de Packrift

Servidor MCP (Model Context Protocol) de producción para Packrift, una tienda de suministros de embalaje en Shopify. Permite a los agentes de IA buscar en el catálogo, obtener precios e inventario en tiempo real, recomendar una caja para un artículo, estimar el envío y generar URLs de pago.

• Stack: Cloudflare Workers, TypeScript (estricto), Hono, Zod, transporte HTTP Streamable

• Base: Shopify Admin GraphQL API (2025-04), tienda packrift.myshopify.com

• Endpoint: POST /mcp, GET /mcp (SSE), GET / (salud), GET /.well-known/mcp/server-card.json

Herramientas

Desarrollo local

Instala Node 24+ y las dependencias:

cd ~/Downloads/packrift-mcp-server
npm install

Secretos locales: ya creados en .dev.vars (ignorado por git):

SHOPIFY_PACKRIFT_TOKEN=shpat_...

Ejecuta el servidor:

npx wrangler dev --port 8787 --local

Prueba de humo del endpoint MCP con curl:

# initialize
curl -s -X POST http://127.0.0.1:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# list tools
curl -s -X POST http://127.0.0.1:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# search
curl -s -X POST http://127.0.0.1:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"poly mailer","limit":3}}}'

Verificación de tipos:

npx tsc --noEmit

Despliegue

La cuenta de Cloudflare se está creando en un proceso separado. Una vez que esté lista y wrangler haya iniciado sesión (wrangler login), ejecuta estos comandos en orden:

cd ~/Downloads/packrift-mcp-server

# 1. Create the KV namespace and copy the printed id into wrangler.toml
#    (replace both `id` and `preview_id` with the same value).
npx wrangler kv namespace create CATALOG_CACHE

# 2. Set the Shopify Admin token as a secret (paste shpat_... when prompted).
npx wrangler secret put SHOPIFY_PACKRIFT_TOKEN

# 3. Deploy. Initial deploy puts the worker on
#    https://packrift-mcp.<account>.workers.dev
npx wrangler deploy

# 4. (Once mcp.packrift.com is CNAME'd to the worker) uncomment the [[routes]]
#    block in wrangler.toml and redeploy.
npx wrangler deploy

Después del despliegue, el endpoint MCP es https://packrift-mcp.<account>.workers.dev/mcp (y posteriormente https://mcp.packrift.com/mcp). La tarjeta del servidor se encuentra en /.well-known/mcp/server-card.json.

Notas de diseño / advertencias

• cartCreate es una mutación de la Storefront API, no de Admin. El resumen solicitaba cartCreate + cartBuyerIdentityUpdate para las tarifas de envío, pero no existen en la API GraphQL de Admin que utiliza este servidor. La ruta de Admin admitida es draftOrderCalculate, que es la que utiliza get_shipping_estimate. Devuelve los mismos datos de tarifas de transportista sin crear un pedido real.

• Análisis de dimensiones. Las dimensiones de los productos de Packrift residen en los metafields custom.specN_value donde el custom.specN_name correspondiente indica "Dimensions" o "Size". El formato es legible por humanos (12 1/8" L x 11 5/8" W x 2 5/8" H). src/dimensions.ts analiza fracciones mixtas y recurre al escaneo del título.

• Colecciones de recomendación. El resumen mencionaba la colección mailer-boxes; ese handle no existe en la tienda en vivo. Usamos mailers-envelopes, boxes-mailers, corrugated-boxes, bubble-wrap-foam, cushioning y ecommerce-fulfillment (verificado mediante la consulta collections el 29-04-2026).

• El mapeo de casos de uso se encuentra en src/tools/recommend_packaging.ts (COLLECTIONS_BY_USE_CASE).

• El handle de la tarifa de envío en la respuesta es una cadena larga y opaca al estilo JWT; así es como Shopify devuelve los handles de tarifas; pásalo a las llamadas posteriores si es necesario.

• Errores: las excepciones de las herramientas se devuelven como { content: [...], isError: true } según la especificación MCP, no como errores JSON-RPC -3260x. Los errores a nivel de protocolo (herramienta desconocida, JSON incorrecto) sí devuelven errores JSON-RPC.

Mapa de archivos

src/
  index.ts                       Hono app + MCP JSON-RPC dispatcher
  shopify.ts                     Admin GraphQL client + id helpers
  dimensions.ts                  Spec-string -> structured dimensions
  server-card.ts                 /.well-known card
  tools/
    search_products.ts
    get_product.ts
    get_pricing.ts
    check_inventory.ts
    recommend_packaging.ts
    get_shipping_estimate.ts
    create_cart_url.ts
wrangler.toml                    Worker config (KV binding, vars, route)
package.json
tsconfig.json
.dev.vars                        Local-only secrets (gitignored)