Packrift MCP 服务器

Name: Packrift MCP Server
Author: Packrift

用于 Packrift（一家 Shopify 包装用品商店）的生产级 MCP（模型上下文协议）服务器。允许 AI 代理搜索目录、获取实时价格和库存、为商品推荐包装盒、估算运费并生成结账 URL。

技术栈: Cloudflare Workers, TypeScript (严格模式), Hono, Zod, Streamable HTTP 传输
后端: Shopify Admin GraphQL API (2025-04), 商店 packrift.myshopify.com
端点: POST /mcp, GET /mcp (SSE), GET / (健康检查), GET /.well-known/mcp/server-card.json

工具

工具	用途
`search_products(query, limit?)`	在整个目录中进行关键词搜索。在 KV 中缓存 5 分钟。
`get_product(handle)`	获取完整产品详情，包括变体、尺寸元字段、重量。
`get_pricing(variant_ids[], quantity?)`	实时单价 + 行总价。从不缓存。
`check_inventory(variant_ids[])`	实时库存数量。从不缓存。
`recommend_packaging(dims, weight, use_case)`	最多 5 个排名靠前的变体建议，包含 0.5–2 英寸的填充空间。
`get_shipping_estimate(zip, country, items[])`	通过 Shopify `draftOrderCalculate` 获取承运商费率。
`create_cart_url(items[], discount_code?, ref?)`	构建 `packrift.com/cart/...?ref=mcp[&discount=...]`。

本地开发

安装 Node 24+ 和依赖项：

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

本地密钥 — 已在 .dev.vars 中创建（已忽略 git）：

SHOPIFY_PACKRIFT_TOKEN=shpat_...

运行服务器：

npx wrangler dev --port 8787 --local

使用 curl 对 MCP 端点进行冒烟测试：

# 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 API。 需求中要求使用 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 集合 — 该句柄在实时商店中不存在。我们使用 mailers-envelopes、boxes-mailers、corrugated-boxes、bubble-wrap-foam、cushioning 和 ecommerce-fulfillment（已通过 collections 查询 2026-04-29 验证）。
用例映射 位于 src/tools/recommend_packaging.ts (COLLECTIONS_BY_USE_CASE) 中。
响应中的运费 handle 是一个很长的、不透明的 JWT 风格字符串 — 这就是 Shopify 返回费率句柄的方式；如果需要，请将其传递给后续调用。
错误：根据 MCP 规范，工具异常作为 { content: [...], isError: true } 返回，而不是作为 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)

Packrift MCP Server

Packrift MCP 服务器

工具

本地开发

部署

设计说明 / 注意事项

文件映射

Resources

Latest Blog Posts

MCP directory API