shoplazza-mcp

Реализация на Python, которая оборачивает Shoplazza OpenAPI (REST) в сервис MCP (Model Context Protocol), позволяющая клиентам с поддержкой MCP, таким как Claude, Cursor, DSH, напрямую читать и записывать данные магазина Shoplazza (товары, заказы, клиенты, остатки, скидки, подписка на webhook и т.д.).

Каталог конечных точек (data/endpoints.json) автоматически собирается из официальной документации скриптом tools/scrape_endpoints.py и охватывает 311 реальных конечных точек и 46 групп ресурсов версии 2026-01.

Возможности

Установка

Требования: Python ≥ 3.10, uv (рекомендуется) или pip.

cd shoplazza-mcp
uv sync          # 创建 .venv 并安装依赖（mcp、httpx）

Если не используете uv:

python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -e .

Конфигурация

Предоставляйте учётные данные через переменные окружения (не записывайте ключи в код и не коммитьте их в репозиторий):

# PowerShell / cmd
set SHOPLAZZA_SHOP_DOMAIN=your-store.myshoplazza.com
set SHOPLAZZA_ACCESS_TOKEN=your-access-token

* Достаточно одного из вариантов: конфигурация для одного магазина SHOPLAZZA_SHOP_DOMAIN + SHOPLAZZA_ACCESS_TOKEN или конфигурация для нескольких магазинов SHOPLAZZA_STORES; если заданы оба, SHOPLAZZA_SHOP_DOMAIN является магазином по умолчанию.

Полный пример см. в .env.example.

Использование с несколькими магазинами

После настройки нескольких магазинов каждый API-инструмент в сервисе получает дополнительный необязательный параметр shop_domain:

export SHOPLAZZA_STORES='{"us.myshoplazza.com":"token-us","de.myshoplazza.com":"token-de"}'

• Без shop_domain → используется магазин по умолчанию (SHOPLAZZA_SHOP_DOMAIN или первый элемент STORES)

• С shop_domain → используется указанный магазин (для неизвестного магазина будет ошибка с перечнем настроенных магазинов)

• shoplazza_list_shops → просмотр всех настроенных магазинов и магазина по умолчанию

• Для каждого магазина действуют отдельные Access-Token и отдельное ведро ограничения частоты (в соответствии с официальным правилом лимита на магазин); магазины не блокируют друг друга

Пример диалога:

«Проверь количество заказов в магазине US за сегодня и посмотри топ-5 товаров по продажам в магазине DE» → модель вызовет shoplazza_orders / shoplazza_products с shop_domain=us.myshoplazza.com и shop_domain=de.myshoplazza.com соответственно.

Пример конфигурации Claude Desktop (несколько магазинов):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_STORES": "{\"us.myshoplazza.com\":\"token-us\",\"de.myshoplazza.com\":\"token-de\"}"
      }
    }
  }
}

Требуемые разрешения API (scope)

При создании/установке приложения в партнёрском центре или авторизации магазина запрашивайте только те scope, которые нужны, следуя принципу минимальных привилегий. Для чтения данных указывайте read_*, для изменений добавляйте одноимённый write_*:

Рекомендуемый набор для сценариев только чтения: read_shop, read_product, read_order, read_customer, read_price_rules, read_gift_cards, read_shop_navigation, read_data. После авторизации можно вызвать инструмент shoplazza_oauth_access_scopes, чтобы проверить, какие scope фактически выданы при этой установке. Полную официальную таблицу соответствия см. в области доступа.

Как получить Access Token

• Публичные приложения: используйте процесс OAuth 2.0 Authorization Code, обменяйте code на access_token (срок действия 1 год, можно обновить с помощью refresh_token).

• Частные / внутренние интеграции: создайте соответствующий токен доступа для приложения и магазина в панели администратора Shoplazza.

Запуск

stdio (локальный MCP-клиент, по умолчанию)

uv run shoplazza-mcp

HTTP (удалённый сервис)

uv run shoplazza-mcp --transport http --host 0.0.0.0 --port 8765

Путь конечной точки по умолчанию — /mcp, его можно изменить с помощью --http-path.

Подключение к MCP-клиентам

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_SHOP_DOMAIN": "your-store.myshoplazza.com",
        "SHOPLAZZA_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Cursor: добавьте сервер в настройках → MCP, конфигурация — в examples/mcp-cursor.json.

Удалённый HTTP (любой клиент): укажите url на http://host:8765/mcp.

Также можно запустить напрямую (debug для просмотра списка инструментов и JSON-RPC взаимодействия):

uv run mcp dev shoplazza-mcp

Примеры использования (диалоги в Claude / Cursor и т.п.)

• «Покажи 10 последних заказов в магазине»

• «Проверь остатки товара abcd-1234»

• «Отмени заказ order-xxx, причина — customer requested»

• «Создай скидку: при покупке от 100 скидка 20»

• «Каким API можно сделать возврат? Поищи конечные точки» → модель вызовет shoplazza_search_endpoints("refund") и затем автоматически вызовет соответствующий endpoint.

Все ответы возвращают исходный пакет API: {code, message, data, api_call_limit}; ответы со списками содержат cursor / pre_cursor в data, для постраничной навигации используйте параметры page_size / per_page.

Разработка и сопровождение

• tools/scrape_endpoints.py: извлекает данные со страницы официальной документации конечных точек и генерирует data/endpoints.json (содержит method/path/параметры/поля тела запроса/структуру ответа для каждой конечной точки).

• Поддержка: чтобы добавить или удалить «часто используемые инструменты», достаточно изменить список CURATED_SLUGS в shoplazza_mcp/tools.py.

• scripts/smoke_test.py: офлайн-смоук-тест (stdio); scripts/http_smoke_test.py: HTTP-смоук-тест.

Безопасность

• Access Token следует передавать только через переменные окружения / конфигурацию клиента, не записывайте его в репозиторий кода.

• Сервис работает только через HTTPS (официальное требование: все конечные точки доступны только по HTTPS).

• При публикации HTTP-сервиса во внешнюю сеть размещайте его в доверенной внутренней сети или добавьте собственную аутентификацию (например, шлюз, межсетевой экран).

Лицензия

MIT