Packrift MCP-Server

Produktions-MCP-Server (Model Context Protocol) für Packrift, einen Shopify-Shop für Verpackungsmaterial. Ermöglicht KI-Agenten das Durchsuchen des Katalogs, den Abruf von Live-Preisen und Lagerbeständen, die Empfehlung von Kartons für Artikel, die Schätzung von Versandkosten und die Erstellung von Checkout-URLs.

• Stack: Cloudflare Workers, TypeScript (strict), Hono, Zod, Streamable HTTP-Transport

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

• Endpunkt: POST /mcp, GET /mcp (SSE), GET / (Health-Check), GET /.well-known/mcp/server-card.json

Tools

Lokale Entwicklung

Installieren Sie Node 24+ und die Abhängigkeiten:

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

Lokale Geheimnisse — bereits in .dev.vars erstellt (gitignored):

SHOPIFY_PACKRIFT_TOKEN=shpat_...

Starten Sie den Server:

npx wrangler dev --port 8787 --local

Testen Sie den MCP-Endpunkt mit 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}}}'

Typ-Prüfung:

npx tsc --noEmit

Bereitstellung

Das Cloudflare-Konto wird in einem separaten Prozess erstellt. Sobald es bereit ist und wrangler angemeldet ist (wrangler login), führen Sie diese Befehle nacheinander aus:

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

Nach der Bereitstellung lautet der MCP-Endpunkt https://packrift-mcp.<account>.workers.dev/mcp (und später https://mcp.packrift.com/mcp). Die Server-Card befindet sich unter /.well-known/mcp/server-card.json.

Design-Hinweise / Vorbehalte

• cartCreate ist eine Storefront-API-Mutation, keine Admin-Mutation. Die Anforderung verlangte cartCreate + cartBuyerIdentityUpdate für Versandraten, aber diese existieren nicht in der Admin-GraphQL-API, die dieser Server verwendet. Der unterstützte Admin-Pfad ist draftOrderCalculate, welcher von get_shipping_estimate verwendet wird. Er gibt dieselben Frachtratendaten zurück, ohne eine echte Bestellung zu erstellen.

• Dimensions-Parsing. Packrift-Produktdimensionen befinden sich in custom.specN_value-Metafeldern, bei denen das zugehörige custom.specN_name „Dimensions“ oder „Size“ lautet. Das Format ist menschenlesbar (12 1/8" L x 11 5/8" W x 2 5/8" H). src/dimensions.ts parst gemischte Brüche und greift auf das Scannen des Titels zurück.

• Empfehlungs-Kollektionen. Die Anforderung erwähnte die Kollektion mailer-boxes – dieses Handle existiert im Live-Shop nicht. Wir verwenden mailers-envelopes, boxes-mailers, corrugated-boxes, bubble-wrap-foam, cushioning und ecommerce-fulfillment (verifiziert via collections-Abfrage vom 29.04.2026).

• Anwendungsfall-Mapping befindet sich in src/tools/recommend_packaging.ts (COLLECTIONS_BY_USE_CASE).

• Versandraten-handle in der Antwort ist eine lange, undurchsichtige JWT-ähnliche Zeichenfolge – so gibt Shopify Raten-Handles zurück; geben Sie diese bei Bedarf an nachfolgende Aufrufe weiter.

• Fehler: Tool-Ausnahmen werden gemäß MCP-Spezifikation als { content: [...], isError: true } zurückgegeben, nicht als JSON-RPC -3260x-Fehler. Fehler auf Protokollebene (unbekanntes Tool, fehlerhaftes JSON) geben JSON-RPC-Fehler zurück.

Dateistruktur

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)