Сервер Hey Harper multi-store Shopify MCP

Крошечный удалённый MCP-сервер, хранящий постоянные токены Admin API всех пяти магазинов Hey Harper и получающий невыполненные / требующие внимания заказы-кандидаты из каждого магазина за одно подключение — без 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. Settings → Apps and sales channels → Develop apps → Create an app (назовите его, например, cowork-unfulfilled-reader).

2. Настройте Admin API scopes и включите (достаточно только чтения):

   • read_orders

   • read_all_orders (позволяет запрашивать заказы старше 60 дней)

   • read_products

   • read_inventory

   • read_fulfillments

   • read_merchant_managed_fulfillment_orders

3. Установите приложение, затем в разделе API credentials откройте Admin API access token (shpat_…). Скопируйте его.

4. Запишите домен myshopify магазина (например, hey-harper-shop-uk.myshopify.com).

В итоге у вас будет пять пар (domain, token). Никогда не коммитьте их и не вставляйте в чат — они попадают прямо в хранилище секретов хостинга на шаге 3.

2. Разверните сервер

В репозитории есть Dockerfile, поэтому подойдёт любой контейнерный хостинг (Render, Railway, Fly.io, VPS). Нужен обычный доступ в интернет и публичный HTTPS URL.

Render (пример, самый простой):

• Web Service → New → подключите этот репозиторий (или «Deploy from a 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/секретах вашего хостинга:

• 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 → Settings → Connectors → Add custom connector:

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

• Auth: укажите bearer-токен (MCP_AUTH_TOKEN), чтобы запросы отправлялись с заголовком Authorization: Bearer <токен>.

Если интерфейс коннектора не позволяет прикрепить статический заголовок, установите MCP_PATH на непредсказуемый путь (например, /mcp/9f3c…) — тогда секретный путь выступает в роли учётных данных. После подключения инструменты heyharper_list_stores, heyharper_pull_store_orders и heyharper_pull_all_stores появятся как доступные.

5. Подключите к ежедневной задаче

Направьте ежедневную задачу Cowork на 9 утра на heyharper_pull_all_stores, затем примените логику классификации (порог опоздания по рабочим дням, правило OOS (только EU/UK/BR/MX), исключения Everstox) в соответствии со спецификацией передачи задач:

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.

Переменные окружения

Локальный запуск

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 для справки и задайте в окружении хостинга (секреты):

• 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 → Settings → Connectors → Add custom connector:

• URL: https://<ваш-хост>/mcp

• Auth: укажите bearer-токен (MCP_AUTH_TOKEN).

Если в вашем тарифе интерфейс коннектора не позволяет прикрепить статический заголовок, задайте MCP_PATH — непредсказуемый путь (например, /9f3c…), и тогда секретный путь выступит как учётные данные.

После подключения инструменты heyharper_list_stores, heyharper_pull_store_orders и heyharper_pull_all_stores появятся в Claude.

5. Настройте ежедневный отчёт

Укажите в задаче вызов heyharper_pull_all_stores и примените логику классификации (она лежит в задаче Cowork, не в сервере), чтобы решить, какие заказы требуют внимания. Затем опубликуйте результат в канале.

Зачем это нужно

Официальный коннектор Shopify держит один магазин за раз и требует повторной OAuth-авторизации при каждом переключении — это делает невозможной автоматическую ежедневную выгрузку. Данный сервер полностью обходит это, используя токены Admin API кастомного приложения и запрашивая все магазины напрямую.

Переменные окружения

Требования к хостингу

• Обычный доступ в интернет.

• Публичный HTTPS URL.

• Возможность запуска Docker-контейнера.

Render (пример, самый простой): New → Web Service → подключите репозиторий (или "Deploy from a Dockerfile"). Render сам определит Dockerfile, выдаст HTTPS и публичный URL.

Fly.io / Railway: укажите Dockerfile так же, как обычно.