Hey Harper マルチストア Shopify MCP サーバー

5店舗すべてのHey Harperストアの永続的なShopify Admin APIトークンを保持し、1つの接続で全ストアの未発送・要対応候補の注文を取得する、小さなリモートMCPサーバーです。switch-shopも、ストアごとのOAuth再認証も不要です。これにより、毎日の「要対応注文」レポートを無人で実行できるようになります。

これが存在する理由

公式のShopifyコネクタは一度に1ストアのみを保持し、ストアを切り替えるたびに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（例、最も簡単）:

• 新規 → Webサービス → このリポジトリを接続（または「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）。必ず設定してください — エンドポイントを保護するベアラートークンです。

• 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

• 認証: ベアラートークン（MCP_AUTH_TOKEN）を提供し、リクエストがAuthorization: Bearer <token>を送信するようにします。

コネクタUIがお使いのプランで静的ヘッダーを添付できない場合の代替案として、MCP_PATHを推測不能なパス（例: /mcp/9f3c…）に設定し、それをURLとして使用する方法があります。秘密のパスが資格情報として機能します。サポートされている場合はベアラートークンが推奨されます。

接続すると、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_*スコープのみ）です。サーバーはストアを変更できません。

環境変数