MCP-сервер Packrift

Промышленный MCP-сервер (Model Context Protocol) для Packrift, магазина упаковочных материалов на Shopify. Позволяет ИИ-агентам искать товары в каталоге, получать актуальные цены и данные об остатках, рекомендовать коробки для товаров, рассчитывать стоимость доставки и создавать ссылки на оформление заказа.

• Стек: Cloudflare Workers, TypeScript (строгий режим), Hono, Zod, Streamable HTTP transport

• Бэкенд: Shopify Admin GraphQL API (2025-04), магазин packrift.myshopify.com

• Эндпоинты: POST /mcp, GET /mcp (SSE), GET / (проверка работоспособности), GET /.well-known/mcp/server-card.json

Инструменты

Локальная разработка

Установите Node 24+ и зависимости:

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

Локальные секреты — уже созданы в .dev.vars (игнорируются git):

SHOPIFY_PACKRIFT_TOKEN=shpat_...

Запустите сервер:

npx wrangler dev --port 8787 --local

Протестируйте эндпоинт MCP с помощью 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}}}'

Проверка типов:

npx tsc --noEmit

Развертывание

Учетная запись Cloudflare создается в отдельном процессе. Как только она будет готова и выполнен вход в wrangler (wrangler login), выполните по порядку:

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

После развертывания эндпоинт MCP будет доступен по адресу https://packrift-mcp.<account>.workers.dev/mcp (а позже https://mcp.packrift.com/mcp). Серверная карта находится по адресу /.well-known/mcp/server-card.json.

Заметки по проектированию / предостережения

• cartCreate — это мутация Storefront API, а не Admin. В задаче требовалось использовать cartCreate + cartBuyerIdentityUpdate для расчета стоимости доставки, но их нет в Admin GraphQL API, который использует этот сервер. Поддерживаемый путь в Admin — draftOrderCalculate, который и использует get_shipping_estimate. Он возвращает те же данные о тарифах перевозчиков, не создавая реальный заказ.

• Парсинг размеров. Размеры товаров Packrift хранятся в метаполях custom.specN_value, где соответствующее поле custom.specN_name содержит значение "Dimensions" или "Size". Формат удобен для чтения (12 1/8" L x 11 5/8" W x 2 5/8" H). src/dimensions.ts обрабатывает смешанные дроби и при необходимости сканирует название товара.

• Коллекции для рекомендаций. В задаче упоминалась коллекция mailer-boxes — такого идентификатора (handle) в реальном магазине нет. Мы используем mailers-envelopes, boxes-mailers, corrugated-boxes, bubble-wrap-foam, cushioning и ecommerce-fulfillment (проверено через запрос collections от 2026-04-29).

• Сопоставление вариантов использования (use case) находится в src/tools/recommend_packaging.ts (COLLECTIONS_BY_USE_CASE).

• handle тарифа доставки в ответе представляет собой длинную непрозрачную строку в стиле JWT — именно так Shopify возвращает идентификаторы тарифов; при необходимости передавайте их в последующие вызовы.

• Ошибки: исключения инструментов возвращаются как { content: [...], isError: true } согласно спецификации MCP, а не как ошибки JSON-RPC -3260x. Ошибки на уровне протокола (неизвестный инструмент, неверный JSON) возвращают ошибки JSON-RPC.

Карта файлов

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)