Hey Harper 다중 스토어 Shopify MCP 서버

Hey Harper의 5개 스토어 전체의 영구 Shopify Admin API 토큰을 보유하고, 단일 연결로 모든 스토어에서 미처리(fulfillment 대기) / 주의 필요 후보 주문을 가져오는 소형 원격 MCP 서버입니다 — switch-shop도, 스토어별 OAuth 재인증도 필요 없습니다. 이것이 매일 "주의 필요 주문" 보고서를 무인으로 실행 가능하게 만드는 핵심입니다.

왜 필요한가

공식 Shopify 커넥터는 한 번에 하나의 스토어만 보유하며, 스토어를 전환할 때마다 OAuth 재인증을 강제합니다 — 예약 작업에는 자동화가 불가능합니다. 이 서버는 사용자 지정 앱 Admin API 토큰(영구, OAuth 불필요)을 사용하고 모든 스토어를 직접 쿼리하여 이 문제를 완전히 우회합니다.

Related MCP server: Shopify MCP

노출되는 도구

각 주문은 정규화 및 강화된 형태로 반환되지만(파싱된 released_hold_at, Everstox 태그 플래그, 라인별 oos), "주의 필요" 여부를 판단하는 것은 의도적으로 하지 않습니다 — 영업일 지연 임계값, OOS 규칙(EU/UK/BR/MX만), Everstox 제외 항목은 Cowork 작업에 유지되어, 재배포 없이 임계값을 조정하고 휴일 달력을 추가할 수 있습니다.

설정 — 단계별 가이드

1. 각 스토어에서 사용자 지정 앱 + 토큰 생성

모든 Hey Harper 스토어 관리자(US, EU, UK, BR, MX)에서:

1. 설정 → 앱 및 판매 채널 → 앱 개발 → 앱 생성(예: cowork-unfulfilled-reader로 이름 지정).

2. Admin API 범위 구성 및 활성화(읽기 전용이면 충분):

   • read_orders

   • read_all_orders (60일 이상 지난 주문 쿼리 허용)

   • read_products

   • read_inventory

   • read_fulfillments

   • read_merchant_managed_fulfillment_orders

3. 앱 설치, API 자격 증명에서 Admin API 액세스 토큰(shpat_…)을 표시하고 복사합니다.

4. 스토어의 myshopify 도메인을 기록합니다(예: hey-harper-shop-uk.myshopify.com).

결과적으로 5개의 (도메인, 토큰) 쌍이 생성됩니다. 이것들을 커밋하거나 채팅에 붙여넣지 마세요 — 3단계에서 호스트의 시크릿 저장소에 직접 입력합니다.

2. 서버 배포

리포지토리에는 Dockerfile이 포함되어 있어 모든 컨테이너 호스트(Render, Railway, Fly.io, VPS)에서 작동합니다. 일반적인 인터넷 액세스와 공개 HTTPS URL이 필요합니다.

Render(예시, 가장 간단):

• 새로 만들기 → 웹 서비스 → 이 리포지토리 연결(또는 "Dockerfile에서 배포").

• Render가 Dockerfile을 자동 감지합니다. 빌드/시작 명령이 필요 없습니다.

• HTTPS와 공개 URL을 자동으로 제공합니다.

Fly.io / Railway: 동일한 방식으로 Dockerfile을 지정합니다.

로컬 테스트:

npm install
npm run build
MCP_AUTH_TOKEN=$(openssl rand -hex 32) HH_UK_DOMAIN=hey-harper-shop-uk.myshopify.com HH_UK_TOKEN=shpat_xxx npm start
# health check:
curl localhost:3000/health

3. 호스트에 환경 시크릿 설정

참고용으로 .env.example을 복사하고 호스트의 env/시크릿 UI에 다음을 설정합니다:

• MCP_AUTH_TOKEN — 긴 임의 문자열(openssl rand -hex 32). 반드시 설정 — 엔드포인트를 보호하는 bearer 토큰입니다.

• HH_US_DOMAIN / HH_US_TOKEN, HH_EU_*, HH_UK_*, HH_BR_*, HH_MX_* — 1단계의 쌍.

도메인과 토큰이 모두 설정된 스토어만 활성화되므로, UK부터 시작하고 토큰을 생성하면서 나머지를 추가할 수 있습니다.

4. Claude에 사용자 지정 커넥터로 추가

claude.ai → 설정 → 커넥터 → 사용자 지정 커넥터 추가에서:

• URL: https://<your-host>/mcp

• 인증: bearer 토큰(MCP_AUTH_TOKEN)을 제공하여 요청이 Authorization: Bearer <token>을 전송하도록 합니다.

커넥터 UI가 해당 플랜에서 정적 헤더를 첨부할 수 없는 경우, 대안으로 MCP_PATH를 추측 불가능한 경로(예: /mcp/9f3c…)로 설정하고 이를 URL로 사용하는 방법이 있습니다 — 비밀 경로가 자격 증명 역할을 합니다. 지원되는 곳에서는 bearer 토큰이 선호됩니다.

연결되면 heyharper_list_stores, heyharper_pull_store_orders, heyharper_pull_all_stores가 도구로 표시됩니다.

5. 일일 보고서 연결

매일 오전 9시 Cowork 작업을 heyharper_pull_all_stores에 연결한 후 분류 로직(핸드오프 사양에 따라 작업에 유지)을 적용합니다:

clock    = releasedHoldAt if hasReleasedHold else processedAt
late     = business_days_since(clock) >= 2      (weekends excluded, warehouse TZ)
shop_oos = anyLineOos                            (only where storeAppliesOos)
excluded = hasOosEverstox OR (hasHoldEverstox AND NOT hasReleasedHold)
           OR (hasSetOnHold AND NOT hasReleasedHold)
needs_attention = (late OR shop_oos) AND NOT excluded

롤업 결과를 #daily-unfulfilled에 게시합니다.

보안 참고 사항

• 토큰은 호스트의 env/시크릿에만 저장됩니다 — 리포지토리에는 절대 저장하지 않습니다(.env는 gitignore 처리됨).

• URL을 공개하기 전에 항상 MCP_AUTH_TOKEN을 설정하세요. 누락된 경우 서버가 경고를 기록합니다.

• 모든 도구는 읽기 전용(read_* 범위만)입니다 — 서버는 스토어를 수정할 수 없습니다.

환경 변수