Packrift MCP 서버

Name: Packrift MCP Server
Author: Packrift

Shopify 포장 용품 스토어인 Packrift를 위한 프로덕션 MCP(Model Context Protocol) 서버입니다. AI 에이전트가 카탈로그를 검색하고, 실시간 가격 및 재고를 확인하며, 상품에 맞는 상자를 추천하고, 배송비를 견적하며, 결제 URL을 생성할 수 있게 합니다.

스택: Cloudflare Workers, TypeScript (strict), 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)`	0.5~2인치 여유 공간을 고려한 최대 5개의 순위별 변형 제안.
`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에 이미 생성됨 (gitignored):

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는 Admin이 아닌 Storefront API 변형입니다. 요구사항에는 배송 요금을 위한 cartCreate + cartBuyerIdentityUpdate가 포함되어 있었으나, 이 서버가 사용하는 Admin GraphQL API에는 존재하지 않습니다. 지원되는 Admin 경로는 draftOrderCalculate이며, get_shipping_estimate가 이를 사용합니다. 실제 주문을 생성하지 않고 동일한 운송업체 요금 데이터를 반환합니다.
치수 파싱. Packrift 상품 치수는 custom.specN_name이 "Dimensions" 또는 "Size"인 경우 custom.specN_value 메타필드에 저장됩니다. 형식은 사람이 읽을 수 있는 형태(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를 사용합니다 (2026-04-29 collections 쿼리를 통해 확인됨).
사용 사례 매핑은 src/tools/recommend_packaging.ts (COLLECTIONS_BY_USE_CASE)에 있습니다.
**응답의 배송 요금 handle**은 긴 불투명한 JWT 스타일 문자열입니다. Shopify가 요금 핸들을 반환하는 방식이며, 필요 시 후속 호출에 그대로 전달하십시오.
오류: 도구 예외는 MCP 사양에 따라 JSON-RPC -3260x 오류가 아닌 { content: [...], isError: true }로 반환됩니다. 프로토콜 수준의 오류(알 수 없는 도구, 잘못된 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