OHMS — Система управления заказами (Order Hub Management System)

Flauraly Flowers and Plants — сервер Python FastMCP, размещенный на зарезервированной виртуальной машине Replit.

Назначение

OHMS предоставляет небольшой, защищенный набор инструментов для работы с заказами и запасами для Violet (и любого другого авторизованного MCP-клиента) через протокол Model Context Protocol. Он централизует доступ к REST API администратора Shopify через шлюз с Bearer-авторизацией, чтобы агенты никогда не имели доступа к исходным учетным данным Shopify.

Архитектура

+-----------------+      Bearer       +------------------------------+
|  MCP Client     |  ---------------> |  OHMS (Replit Reserved VM)   |
|  (Violet, etc.) |   /mcp or /sse    |                              |
+-----------------+                   |  Starlette parent app        |
                                      |  +-- /health (open)          |
                                      |  +-- /mcp   (Streamable HTTP)|
                                      |  +-- /sse   (SSE fallback)   |
                                      |  +-- BearerAuthMiddleware    |
                                      +--------------+---------------+
                                                     |
                                                     v
                                      +------------------------------+
                                      |  Shopify Admin REST API      |
                                      +------------------------------+

И /mcp (потоковый HTTP), и /sse (резервный вариант Server-Sent Events) подключены одновременно, поэтому работает любой транспортный профиль MCP-клиента.

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

OHMS проходит аутентификацию в Shopify через предоставление учетных данных OAuth 2.0 client_credentials. Сервер никогда не хранит долгоживущий SHOPIFY_ACCESS_TOKEN; вместо этого он хранит пару SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET и по запросу создает краткосрочный токен доступа через https://{shop}.myshopify.com/admin/oauth/access_token. Созданный токен кэшируется в памяти с буфером синхронизации часов в 5 минут и автоматически пересоздается (или при получении 401/403 от любого последующего вызова). Все значения считываются через os.environ.get(...). Ничего не зашито в код.

См. .env.example для шаблона с заполнителями.

Локальная разработка (Windows)

OHMS считывает .env только при локальном запуске (через python-dotenv). Загрузите свой .env из хранилища секретов Windows, защищенного DPAPI, вместо ввода секретов в виде обычного текста:

# 1. Pull each secret from DPAPI into the local .env (PowerShell pseudocode)
$secrets = @("OHMS_API_TOKEN","SHOPIFY_STORE_URL","SHOPIFY_CLIENT_ID","SHOPIFY_CLIENT_SECRET","SHOPIFY_API_VERSION","PRINTER_IP")
foreach ($k in $secrets) {
    $v = Unprotect-DpapiSecret -Name $k    # your local helper
    Add-Content .env "$k=$v"
}

# 2. Run the server
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

Сервер прослушивает http://0.0.0.0:8080 по умолчанию. Проверка:

curl http://localhost:8080/health
# => OHMS OK

Развертывание на Replit

1. Создайте проект Replit и импортируйте эту папку.

2. На панели Secrets установите все переменные из .env.example (используя реальные значения — никогда не вставляйте их в какой-либо зафиксированный файл).

3. Убедитесь, что в .replit указано deploymentTarget = "reserved_vm" и порт 8080 -> 80.

4. Разверните. Публичный URL: https://ohms-server.crashzero9.replit.app.

5. Проверьте оба транспорта:

curl https://ohms-server.crashzero9.replit.app/health
curl -H "Authorization: Bearer $OHMS_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
     https://ohms-server.crashzero9.replit.app/mcp

Реестр инструментов

Статус фаз

• Фаза 1 (текущая): Каркас MVP, Bearer-авторизация, шесть инструментов (4 рабочих + 2 заглушки), развертывание на зарезервированной виртуальной машине Replit, базовый набор тестов pytest.

• Фаза 2 (запланированная): Замена статического bearer на OAuth 2.1, полноценный драйвер DoorDash, реальный драйвер сетевого принтера, структурированное логирование с маскированием секретов, ограничение частоты запросов (rate limiting).

Примечания по безопасности

• Никакие секретные значения не появляются ни в одном зафиксированном файле.

• Заголовки Authorization и полные тела ответов Shopify никогда не логируются.

• /health возвращает только буквальную строку OHMS OK — никакой информации о версии, окружении или путях.

• Все вызовы httpx имеют явный тайм-аут 30 секунд.