Hey Harper 多店铺 Shopify MCP 服务器

一个微型的远程 MCP 服务器，持有全部五个 Hey Harper 店铺的永久 Shopify Admin API 令牌，并通过一次连接拉取所有店铺中未发货/需要注意的候选订单——无需 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）。

你最终会得到五对 (domain, token)。切勿提交这些信息或将其粘贴到聊天中——它们会直接进入第 3 步中主机的密钥存储。

2. 部署服务器

该仓库附带了一个 Dockerfile，因此任何容器主机都可以使用（Render、Railway、Fly.io、VPS）。它必须具有正常的互联网访问权限和一个公共 HTTPS URL。

Render（示例，最简单）：

• 新建 → Web Service → 连接此仓库（或“从 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 作为参考，并在主机的环境/密钥 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 已被 gitignore 忽略）。

• 在公开 URL 之前，请务必设置 MCP_AUTH_TOKEN；如果缺少该变量，服务器会记录警告。

• 所有工具都是只读的（仅限 read_* 作用域）——服务器无法修改你的店铺。

环境变量