Packrift MCP

Servidor MCP remoto para el catálogo de empaques preparados para IA de Packrift y los flujos de trabajo de empaques de comercio electrónico.

GitHub
1

Documentación

Servidor Packrift MCP

Servidor MCP (Model Context Protocol) de producción para la adquisición de empaques con especificación exacta de Packrift. Caso de uso principal: encontrar el suministro de empaque adecuado para un artículo, SKU o necesidad de reorden determinados, y luego confirmar precio en vivo, inventario, envío y transferencia al carrito.

  • Stack: Cloudflare Workers, TypeScript (strict), Hono, Zod, Streamable HTTP transport
  • Respaldo: Shopify Admin GraphQL API (2025-04), tienda packrift.myshopify.com
  • Endpoint: POST /mcp, GET /mcp (SSE), GET / y GET /start (página de inicio de MCP), GET /.well-known/mcp/server-card.json
  • Guía de instalación: consulta llms-install.md para la configuración de clientes MCP remotos.
  • Puerta de descubrimiento: los flujos de búsqueda de productos, reorden, cotización y transferencia al carrito están restringidos a registros del catálogo de Packrift aprobados por IA cuando está involucrada la selección de SKU.

Configuración de cliente MCP remoto

El endpoint público de Packrift está alojado en:

https://mcp.packrift.com/mcp

Página de inicio rápida para desarrolladores, agentes y revisores de directorios:

https://mcp.packrift.com/start

Las transferencias de directorios y socios pueden usar enlaces de inicio rastreados sin cambiar el endpoint de MCP. Usa un slug de origen en minúsculas con letras, números y guiones bajos:

https://mcp.packrift.com/r/start/{source}

La página de inicio también muestra controles de copia específicos de la fuente cuando recibe una fuente:

https://mcp.packrift.com/start?utm_source={source}

Esas transferencias registran telemetría agregada de intención de instalación: las búsquedas de /r/config/{source} aparecen como mcp_tracked_config_fetches, las aperturas de /r/install/{source}/{target} aparecen como mcp_install_intent, y los controles de copia registran mcp_install_copy por fuente y destino para que las transferencias de socios y directorios puedan evaluarse antes de que aparezcan eventos de carrito posteriores.

Los slugs personalizados de socios, campañas, directorios y flujos de trabajo de agentes están permitidos sin cambios de código siempre que coincidan con ^[a-z0-9_]{2,64}$. Ejemplos: mcpservers_org, agency_partner, browser_agent_demo, newsletter_mcp.

Cuando un host de directorio o agente quiere un archivo de configuración con atribución de fuente en lugar de una página de inicio HTML, usa:

https://mcp.packrift.com/r/config/{source}

Las búsquedas de configuración rastreadas se exponen por fuente en https://mcp.packrift.com/ai/mcp-usage-snapshot.json.

Para una acción de instalación rastreada específica de destino, usa:

https://mcp.packrift.com/r/install/{source}/{target}

Los destinos comunes incluyen generic_streamable_http, stdio_mcp_remote, claude_code, codex, claude_desktop, cursor_windsurf_vscode y cline.

Los clientes MCP que admiten servidores HTTP remotos o Streamable HTTP pueden agregar Packrift con:

{
  "mcpServers": {
    "packrift": {
      "type": "http",
      "url": "https://mcp.packrift.com/mcp"
    }
  }
}

Los usuarios de Cline deben usar el destino Cline rastreado, que devuelve configuración nativa de Cline streamableHttp:

https://mcp.packrift.com/r/install/cline_mcp_marketplace/cline?format=json

Los hosts que solo aceptan comandos MCP stdio locales pueden usar el destino rastreado stdio_mcp_remote. Ejecuta npx mcp-remote como un puente ligero y aún reenvía cada llamada al endpoint alojado de Packrift:

https://mcp.packrift.com/r/install/{source}/stdio_mcp_remote?format=json

Conector alojado y listados de directorios

Usa el endpoint alojado anterior cuando sea posible. No requiere clave API del comprador y expone la superficie comercial actual de 15 herramientas de Packrift con especificación exacta.

Notas de versión del listado fuente de Glama

El conector Glama alojado debe seguir siendo el destino principal de tráfico de Glama. El listado separado del servidor fuente de Glama puede usar este repositorio para verificaciones de versión y calidad, pero debe seguir apuntando a los usuarios al endpoint MCP alojado sin autenticación anterior.

  • Dockerfile inicia el servidor MCP de Packrift en PORT=8787.
  • glama.json es el archivo de reclamación del mantenedor del listado fuente.
  • smithery.yaml proporciona metadatos de contenedor compatibles con Glama/Smithery con un esquema de configuración vacío, para que las verificaciones de versión del listado fuente no infieran un token de comprador requerido.
  • Ejecutar el contenedor sin SHOPIFY_PACKRIFT_TOKEN aún expone el descubrimiento de MCP: tools/list devuelve la superficie actual de 15 herramientas y resources/list devuelve los recursos públicos de IA/MCP.
  • SHOPIFY_PACKRIFT_TOKEN no es necesario para el descubrimiento de MCP, el escaneo de directorios ni el uso del conector alojado. Solo se requiere para llamadas de herramientas de catálogo, precios, inventario, envío y carrito en vivo respaldadas por Shopify autoalojadas.
  • El listado fuente no debe crear una CLI de Packrift ni una superficie de comprador separada; debe publicar/sincronizar el repositorio existente y mantener el runtime canónico en https://mcp.packrift.com/mcp.

Imagen de contenedor

El endpoint alojado público anterior es la ruta de integración principal y el manifiesto canónico server.json es solo remoto. Aún se publica una imagen de contenedor para el desarrollo local y entornos que requieren explícitamente una superficie de instalación autoalojada estilo paquete:

docker pull ghcr.io/packrift/packrift-mcp:latest
docker run --rm -p 8787:8787 \
  -e SHOPIFY_PACKRIFT_TOKEN=<shopify_admin_api_token> \
  ghcr.io/packrift/packrift-mcp:latest

También puedes construir la imagen desde este repositorio:

docker build -t packrift-mcp .
docker run --rm -p 8787:8787 \
  -e SHOPIFY_PACKRIFT_TOKEN=<shopify_admin_api_token> \
  packrift-mcp

Variables de entorno opcionales:

  • PORT tiene como valor predeterminado 8787
  • SHOPIFY_STORE_DOMAIN tiene como valor predeterminado packrift.myshopify.com
  • SHOPIFY_API_VERSION tiene como valor predeterminado 2025-04
  • STOREFRONT_DOMAIN tiene como valor predeterminado packrift.com
  • SHOPIFY_PACKRIFT_TOKEN es opcional para la introspección de MCP y el escaneo de directorios, pero se requiere al autoalojar herramientas de catálogo, precios, inventario, envío y carrito en vivo respaldadas por Shopify

El contenedor usa una caché en memoria en lugar de Cloudflare KV. Está diseñado para descubrimiento y pruebas de cliente; el servidor de producción sigue siendo el endpoint de Cloudflare Workers en https://mcp.packrift.com/mcp.

Superficies de descubrimiento de IA

IndexNow de activación de fuente

Notifica a IndexNow sobre las URLs existentes específicas de fuente para el paquete de evaluación MCP, inicio, instalación, primera ejecución y activación:

npm run submit:source-activation-indexnow

El script verifica previamente https://mcp.packrift.com/ai/mcp-source-activation-sitemap.xml, escribe artefactos bajo outputs/source-activation-indexnow/ y envía solo URLs MCP alojadas existentes. No crea una nueva CLI, superficie para compradores, ruta de pago ni envío a directorios.

Herramientas

Las herramientas están orientadas a la compra por especificaciones exactas, no a la navegación genérica. Usa find_packaging_for_item cuando el comprador tenga dimensiones del artículo o una pregunta sobre ajuste; usa las herramientas de SKU y especificaciones exactas cuando el comprador esté reponiendo un producto conocido.

HerramientaPropósito
find_packaging_for_item(item_length_in, item_width_in, item_depth_in, item_weight_lb, use_case)Principal. Largo/Ancho/Alto + peso + caso de uso → SKUs de embalaje clasificados que ajustan. Úsala para preguntas de ajuste más pequeño, caja vs. sobre acolchado, y estilo Uline por tamaño.
search_products(query, limit?)Respaldo por palabras clave cuando se desconocen las dimensiones, como cinta kraft, sobre acolchado de burbujas, kit de inicio o etiquetas resistentes a la intemperie. Caché de 5 min en KV.
get_product(handle)Detalle completo del producto, incluyendo variantes, dimensiones/metacampos, peso, stock y URL del producto.
get_pricing(variant_ids[], quantity?)Precio unitario en vivo y total de línea antes de la entrega a la compra. variant_ids deben ser IDs numéricos de variantes de Shopify codificados como cadenas. Nunca se almacena en caché.
check_inventory(variant_ids[])Verificación de inventario en vivo antes de recomendar o construir un carrito. variant_ids deben ser IDs numéricos de variantes de Shopify codificados como cadenas. Nunca se almacena en caché.
get_shipping_estimate(zip, country, items[])Tarifas de transportista para un carrito seleccionado mediante Shopify draftOrderCalculate.
get_cart_handoff_candidates(limit?, family?, sku?)SKUs priorizados y seleccionados con argumentos create_cart_url listos, enlaces de SKU/producto/reorden/cotización/carrito y secuencia requerida de confirmación en vivo.
create_cart_url(items[], discount_code?, ref?)Entrega final del carrito. Construye una URL de aterrizaje de carrito Packrift visible para GA4 más el permalink final packrift.com/cart/... con ref=mcp y campos de atribución de comercio con IA.
prepare_purchase_handoff(sku, quantity?, buyer_confirmed?)Ruta rápida de SKU exacto. Confirma el producto, precio en vivo e inventario, luego devuelve una URL de carrito rastreada solo cuando buyer_confirmed=true.
compare_alternatives(requested_spec, family?, competitor_reference?, limit?)Clasifica alternativas Packrift seleccionadas para solicitudes abiertas del comprador, incluyendo especificaciones de embalaje estilo competidor.
pack_calculator(item, padding?, use_case?, limit?)Calcula dimensiones interiores protegidas y devuelve candidatos de cajas o sobres acolchados con guía de relleno de espacios vacíos.
inventory_status(variant_ids?, sku?, handle?, quantity?)Total en vivo y estado de inventario Shopify a nivel de ubicación para SKUs exactos, handles o IDs de variante.
get_reorder_link(sku, handle?)URL de reorden, URL de producto y texto de especificación de compra para un SKU de catálogo o handle.
get_bulk_quote_link(requested_spec, family?, sku?, quantity?)URL de cotización masiva rastreada para flujos de trabajo sin coincidencia exacta, gran volumen o revisión de adquisiciones.
explain_no_exact_match(requested_spec, missing_or_mismatched_fields?)Explica por qué un producto cercano no debe presentarse como exacto, luego enruta a acciones seguras siguientes y recuperación de cotización.

Prompts y recursos MCP

El servidor anuncia prompts y recursos además de las herramientas.

Prompts:

  • find_exact_packaging_spec
  • fit_item_then_prepare_cart
  • review_cart_handoff_candidates
  • reorder_packrift_sku
  • prepare_cart_handoff
  • request_bulk_quote_for_no_match
  • copy_procurement_spec
  • find_box_by_lwh
  • find_label_by_size_material_printer

Los recursos incluyen el corpus de productos aprobados por IA, registros markdown/JSON por SKU, JSONL de rutas de compra, candidatos de entrega de carrito MCP, manual de activación de carrito MCP, directorios de entrega medidos con rutas de carrito, archivos de familias de especificaciones exactas, política de no coincidencia exacta, rutas de compra seguras para rastreadores, superficie de comercio UCP nativa de Shopify, catálogo inicial UCP, kit de construcción de tienda y feed de importación plano para estanterías de embalaje y suministros de envío seleccionados.

Ejemplos de comercio con IA de especificaciones exactas

Packrift está optimizado para la compra de embalaje con especificaciones exactas: los agentes no deben tratar tamaños, materiales, colores, adhesivos, clasificaciones de resistencia o cantidades de caja cercanas como sustitutos exactos. Si no hay una coincidencia exacta aprobada por IA, enruta al comprador a reordenar, explicación de no coincidencia o recuperación de cotización masiva en lugar de forzar un sustituto.

Familias de pedidos actuales de ChatGPT de pago / tarjetas de producto que están representadas en el corpus público:

  • SKU 1066: cajas de cartón kraft ECT-32 de 10 x 6 x 6, 25/paquete
  • SKU MFL1295: sobres para correo de literatura autosellantes blancos de 12 1/8 x 9 1/4 x 5, 50/paquete
  • SKU LL251WR: etiquetas láser de poliéster resistentes a la intemperie de 2 5/8 x 1, 3000/caja

Desarrollo local

Instala Node 24+ y las dependencias:

cd ~/Downloads/packrift-mcp
npm install

Usa /Users/farhan/Downloads/packrift-mcp como árbol de trabajo canónico de producción. El checkout más antiguo /Users/farhan/Downloads/packrift-mcp-server es un duplicado heredado y no debe usarse para despliegues de Worker porque puede sobrescribir mcp.packrift.com con rutas/herramientas obsoletas.

Los secretos locales pertenecen a .dev.vars (ignorado por git). No pegues tokens reales en este README, issues, envíos a directorios, capturas de pantalla o hilos de soporte de terceros.

SHOPIFY_PACKRIFT_TOKEN=<shopify_admin_api_token>

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

Prueba de humo de la ruta de entrega de carrito alojado sin crear un pedido ni recolectar pago:

npm run smoke:cart-handoff

Esta verificación sintética llama al endpoint MCP alojado actual, verifica get_cart_handoff_candidates -> get_product -> get_pricing -> check_inventory -> create_cart_url, y comprueba la ruta de aterrizaje del carrito MCP. Escribe JSON y evidencia en Markdown bajo outputs/mcp-cart-handoff-smoke/. Agrega -- --sku LL251WR --qty 1 para probar otro SKU aprobado por IA. Usa -- --verify-final-cart solo cuando se verifique intencionalmente el redireccionamiento final del carrito de Shopify.

GitHub Actions también ejecuta las pruebas de humo alojadas cada seis horas y en despacho manual a través de .github/workflows/mcp-live-smoke.yml. El trabajo programado verifica tanto 1066 como LL251WR, luego sube artefactos de evidencia de humo y captura. Ejecuta npm run check:distribution para el directorio más amplio y el monitor de registros; sale con código distinto de cero solo cuando una superficie rastreada tiene un estado fail real.

Actualiza el bloque de SKU prioritarios llms-full.txt a partir de la actividad reciente de artículos GA4 unida al catálogo aprobado por IA y al inventario en vivo de Shopify:

npm run build:llms-full -- \
  --ga4-items /path/to/packrift-ga4-items.csv \
  --approved-jsonl /path/to/packrift-ai-approved-products.jsonl \
  --limit 20

El bloque público generado no debe incluir rutas locales, notas internas ni detalles de campaña no públicos. Se escribe un informe JSON privado bajo outputs/llms-full-priority-skus/.

Para ejecutar toda la ruta de actualización, extrae informes GA4 frescos, publica la anulación pública llms-full.txt en Workers KV, purga las URLs de agente públicas y verifica las superficies en vivo:

npm run refresh:llms-full -- --publish-kv

Esto actualiza la clave KV static-override:llms-full.txt. El Worker sirve esa anulación después del despliegue actual, por lo que las actualizaciones futuras de SKU prioritarios no requieren desplegar cambios no relacionados en el código fuente del Worker.

Verifica la disponibilidad llms-full.txt orientada a rastreadores en seis agentes de usuario de IA:

npm run check:static-availability -- --samples-per-ua 200 --concurrency 30

Esto escribe JSON y evidencia en Markdown bajo outputs/static-availability/. La instantánea del embudo también ejecuta esta verificación e informa tasa de fallos, tasa de 5xx, validación de contenido y latencia p95.

Actualiza la prueba completa del embudo MCP, incluida la costura de pedidos de Shopify de primera parte para atributos de carrito MCP:

npm run snapshot:funnel

La instantánea lee el endpoint protegido por token https://mcp.packrift.com/admin/mcp-orders, escanea pedidos recientes de Shopify para atributos de carrito MCP como packrift_mcp_key, packrift_ai_id y utm_source=chatgpt-mcp, e informa recuento de pedidos atribuidos e ingresos junto con evidencia de aterrizaje de carrito GA4. El endpoint de administración requiere MCP_STATS_TOKEN y no expone PII de clientes.

Pública la prueba de visitantes GA4 saneada desde esa instantánea local a la superficie pública del Worker:

npm run publish:ga4-funnel-proof -- --publish-kv

Esto actualiza https://mcp.packrift.com/ai/mcp-ga4-funnel-proof.json y .md sin exponer rutas locales, filas CSV sin procesar, filas de pedidos o credenciales. La instantánea pública del embudo también lee esta prueba para la puerta de miles de visitantes calificados cuando está disponible.

Actualiza la evidencia del directorio MCP:

npm run check:distribution
npm run build:directory-submission-pack

La verificación de distribución informa qué directorios MCP públicos están actualizados, obsoletos, bloqueados o fallando. El paquete de envío convierte filas obsoletas en campos de listado listos para copiar, URLs de prueba en vivo y la próxima acción de actualización para cada directorio.

Verifica el centro de captura de todos los agentes:

npm run check:agent-capture
npm run build:agent-capture-outreach

Esto verifica que https://mcp.packrift.com/ai/all-agent-capture.json y .md, https://mcp.packrift.com/ai/mcp-adoption-kit.json y .md, https://mcp.packrift.com/ai/mcp-install-matrix.json y .md, https://mcp.packrift.com/ai/mcp-usage-snapshot.json y .md, y https://mcp.packrift.com/ai/mcp-agent-adoption-progress.json, .md y .html, y https://mcp.packrift.com/ai/mcp-buyer-use-cases.json, .md y .html, y https://mcp.packrift.com/ai/mcp-cart-activation.json, .md y .html, y https://mcp.packrift.com/ai/mcp-workflow-gallery.json, .md y .html, y https://mcp.packrift.com/ai/browser-agent-bridge.json y .md, y https://mcp.packrift.com/SKILL.md, y https://mcp.packrift.com/ai/mcp-directory-refresh.json y .md, y https://mcp.packrift.com/ai/mcp-directory-submit-actions.json y .md, y https://mcp.packrift.com/ai/mcp-reviewer-activation.json y .md, y el centro de comando de activación en https://mcp.packrift.com/r/activate, el HTML de cola de activación de fuente en https://mcp.packrift.com/ai/mcp-source-activation-queue.html, el ejecutor de activación por oleadas y captura completa de fuente protegida en https://mcp.packrift.com/ai/mcp-activation-wave.json, la cola de tareas de activación externa seleccionada en https://mcp.packrift.com/ai/mcp-external-activation-brief-tasks.jsonl, las exportaciones compactas de tareas seleccionadas en https://mcp.packrift.com/ai/mcp-external-activation-brief-tasks.jsonl?compact=1 y https://mcp.packrift.com/ai/mcp-external-activation-brief-tasks.csv?compact=1, el ejecutor de navegador en https://mcp.packrift.com/r/activate/generic?format=html, y el script de activación de shell en https://mcp.packrift.com/r/activate/generic?format=sh, y https://mcp.packrift.com/ai/mcp-eval-pack.json y .md, y https://mcp.packrift.com/ai/agent-capture-outreach.json y .md están en vivo, anunciados en resources/list, incluyen las superficies centrales de agentes, ruta de instalación/prueba de primeros cinco minutos, ejemplos de desarrollador de copiar y pegar, matriz de instalación lista para copiar, instantánea de uso pública, tablero de progreso de adopción de agentes, mapa de flujo de trabajo del comprador, manual de activación de carrito, galería de flujos de trabajo, paquete de evaluación, puente de agente de navegador, paquete de actualización de directorios, cola de acciones de envío a directorio, centro de comando de activación de fuente, entrega de activación para revisores, paquete de divulgación de captura de agentes, carril candidato de Browserbase Browse y SKILL.md raíz, y preservan la regla de que Packrift usa el endpoint MCP alojado en lugar de una superficie CLI duplicada. La compilación de divulgación escribe mensajes de actualización de directorios obsoletos listos para copiar, briefs de candidatos de Browserbase Browse, enlaces de prueba y fragmentos de instalación MCP bajo outputs/agent-capture-outreach/.

Despliegue

El endpoint de producción es https://mcp.packrift.com/mcp. Usa el endpoint alojado para compradores, revisores de directorios e integraciones de agentes. Solo despliega un worker autoalojado cuando estés actualizando el servicio de producción o probando un fork controlado.

Al desplegar con una sesión autorizada de Cloudflare, ejecuta:

cd ~/Downloads/packrift-mcp

# 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 when prompted.
#    Never write the token into this repository or public documentation.
npx wrangler secret put SHOPIFY_PACKRIFT_TOKEN

# 3. Deploy.
npx wrangler deploy

# 4. Verify the public hosted endpoint after deploy.
curl -sS https://mcp.packrift.com/start >/dev/null

La tarjeta del servidor está en https://mcp.packrift.com/.well-known/mcp/server-card.json.

Notas de diseño / advertencias

  • cartCreate es una mutación de Storefront API, no Admin. La solicitud pidió cartCreate + cartBuyerIdentityUpdate para tarifas de envío, pero esos no existen en la API GraphQL de Admin que usa este servidor. La ruta Admin compatible es draftOrderCalculate, que es lo que usa get_shipping_estimate. Devuelve los mismos datos de tarifas de transportista sin crear un pedido real.
  • Análisis de dimensiones. Las dimensiones de productos Packrift viven en metacampos custom.specN_value donde el custom.specN_name coincidente dice "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 a escanear el título.
  • Colecciones recomendadas. La solicitud mencionó 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 2026-04-29).
  • Mapeo de casos de uso está en src/tools/recommend_packaging.ts (COLLECTIONS_BY_USE_CASE).
  • Tarifa de envío handle en la respuesta es una cadena larga opaca de estilo JWT — así devuelve Shopify los handles de tarifas; pásalo a llamadas posteriores si es necesario.
  • Errores: las excepciones de 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 mal formado) 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
    exploration_tools.ts
    procurement_links.ts
wrangler.toml                    Worker config (KV binding, vars, route)
package.json
tsconfig.json
.dev.vars                        Local-only secrets (gitignored)

Páginas de descubrimiento de SKU para ventas con IA

Packrift publica páginas de SKU de comercio con IA para agentes de compra con especificaciones exactas.