lightspeed-x-mcp

Сервер Model Context Protocol для Lightspeed X (Lightspeed Retail POS, платформа, ранее известная как Vend). Он предоставляет Claude или любому MCP-клиенту доступ только для чтения к продажам, запасам, товарам и клиентам вашего магазина, и сам выполняет агрегацию: выручка, единицы, себестоимость, валовая прибыль, маржа, скидка, средний чек и размер корзины, сгруппированные по любому нужному вам измерению.

Только чтение по построению. Каждый инструмент отправляет GET-запросы. В этом сервере нет ни одного пути кода, который мог бы создавать, обновлять или удалять что-либо в вашем аккаунте, так что вы можете подключить его к работающему розничному бизнесу, не беспокоясь об этом.

"What sold best yesterday?"                → lightspeed_sales_report
"Revenue by store last week"               → lightspeed_sales_report, group_by: outlet
"Which SKUs need reordering?"              → lightspeed_inventory_report, status: reorder_needed
"What are our busiest hours?"              → lightspeed_sales_report, group_by: hour
"Margin by brand this month"               → lightspeed_sales_report, group_by: brand
"Pull up invoice 162220"                   → lightspeed_list_sales

Зачем это существует

API Lightspeed X — пережиток эпохи Vend, и у него есть несколько острых углов, из-за которых наивные клиенты либо работают медленно, либо тихо ошибаются. Этот сервер обрабатывает их, чтобы модели не приходилось:

Как выводится математика выручки

Проверено на 200 последовательных реальных продажах. Каждая сошлась с собственным totals.price продажи с точностью до двух центов:

line revenue excl tax = line_items[].pricing.total        (net of discount, already x quantity)
line COGS             = line_items[].pricing.cost_total
line discount given   = line_items[].pricing.discount_total
line tax              = line_items[].tax.total

Три дополнительные проверки на реальных данных, все точные:

• Сумма дневной выручки за неделю равна общему итогу недели.

• Строка торговой точки в отчёте group_by: outlet равна тому же отчёту, перезапущенному с серверным фильтром этой торговой точки.

• Сумма сумм, внесённых по типу оплаты, равна выручке с учётом налога.

Related MCP server: Toast MCP Server

Установка

Вариант 1: как плагин Claude Code (рекомендуется)

Три команды, без клонирования, без сборки, без правки путей:

/plugin marketplace add genvjacobc/lightspeed-x-mcp
/plugin install lightspeed-x@lightspeed-x-mcp
/lightspeed-x:setup

Третья команда запускает встроенный навык настройки, который проведёт вас через получение токена, запишет его в нужное место и проверит соединение с вашим живым аккаунтом, прежде чем сообщит, что всё работает.

Плагин также поставляется с навыком reports, чтобы Claude знал, какой инструмент отвечает на какой тип розничного вопроса и как читать полученные числа.

Учётные данные хранятся в ${CLAUDE_PLUGIN_DATA}/credentials.env — каталоге для каждого пользователя, который переживает обновления плагина. Ничего не передаётся между машинами или коллегами.

Обратите внимание, что /plugin uninstall удаляет этот каталог, поэтому удаление и повторная установка означают повторный запуск настройки. Сам токен остаётся активным в Lightspeed независимо от этого, так что отзовите его там, если закончили с ним.

Вариант 2: как отдельный MCP-сервер

git clone https://github.com/genvjacobc/lightspeed-x-mcp.git
cd lightspeed-x-mcp
npm install
npm run build

Требуется Node 18 или новее.

Получение API-токена

В бэк-офисе Lightspeed X: Setup → Personal Tokens → Add Personal Token. Скопируйте его до закрытия диалога; он показывается только один раз.

Два ограничения, о которых стоит знать перед планированием развёртывания:

• Только администраторы могут создавать персональные токены, и Lightspeed ограничивает эту функцию тарифами Plus. Если Personal Tokens не появляется в разделе Setup, кто-то с правами администратора должен создать токен для вас.

• Lightspeed не предлагает токены только для чтения. Токен несёт все права пользователя, который его создал. Этот сервер отправляет только GET, но сам токен — это универсальное учётное данное, поэтому обращайтесь с ним как с паролем и отзывайте его на том же экране, если он утёк.

Проверка работы

npm run doctor

Это проверяет ваши учётные данные, вызывает живой API и называет точную причину любой ошибки. Неправильный домен магазина и неверный токен оба возвращают HTTP 401 от Lightspeed, поэтому доктор сообщает обе возможности, а не гадает.

Настройка

Скопируйте .env.example в .env и заполните данные вашего магазина:

LIGHTSPEED_DOMAIN=mystore
LIGHTSPEED_TOKEN=your_personal_token

LIGHTSPEED_DOMAIN принимает голый префикс (mystore), хост (mystore.retail.lightspeed.app) или полный URL. Все три варианта разрешаются в одно и то же место.

Несколько магазинов. Любая пара LIGHTSPEED_<NAME>_DOMAIN + LIGHTSPEED_<NAME>_TOKEN определяет аккаунт с именем <name> в нижнем регистре. Инструменты затем принимают необязательный аргумент account:

LIGHTSPEED_NORTH_DOMAIN=northstore
LIGHTSPEED_NORTH_TOKEN=token_for_north
LIGHTSPEED_SOUTH_DOMAIN=southstore
LIGHTSPEED_SOUTH_TOKEN=token_for_south
LIGHTSPEED_DEFAULT_ACCOUNT=north

Значения, уже присутствующие в окружении, всегда имеют приоритет над файлом .env, поэтому хост, который внедряет учётные данные напрямую, получает преимущество.

Регистрация в Claude Code (только для отдельного пути)

Пропустите это, если вы установили плагин; плагин регистрирует сервер сам.

claude mcp add lightspeed-x -s user -- node /absolute/path/to/lightspeed-x-mcp/dist/index.js

Или добавьте его в конфиг вручную:

{
  "mcpServers": {
    "lightspeed-x": {
      "command": "node",
      "args": ["/absolute/path/to/lightspeed-x-mcp/dist/index.js"],
      "env": {
        "LIGHTSPEED_DOMAIN": "mystore",
        "LIGHTSPEED_TOKEN": "your_personal_token"
      }
    }
  }
}

Для Claude Desktop тот же блок помещается в claude_desktop_config.json.

Проверьте локально с помощью MCP Inspector:

npm run inspect

Инструменты

lightspeed_sales_report

Главное событие. Агрегирует диапазон дат и группирует его.

| Outlet          |   Revenue | Units | Sales | Basket value | Gross profit | Margin |
| --------------- | --------: | ----: | ----: | -----------: | -----------: | -----: |
| South Lincoln   | $3,401.60 |   193 |    91 |       $37.38 |    $2,342.35 |  68.9% |
| York            | $3,222.86 | 159.2 |    73 |       $44.15 |    $2,238.77 |  69.5% |

lightspeed_list_sales

Отдельные транзакции, сначала новые, с опциональным разворачиванием позиций. Для изучения одного чека, аудита итога или просмотра возвратов. Фильтры по outlet_id, customer_id и min_total.

lightspeed_inventory_report

Остатки на складе, объединённые с названиями товаров и торговых точек, с розничной и закупочной стоимостью того, что на полке.

status — аргумент, который имеет значение:

group_by сворачивается до product, outlet, category, brand или supplier, что позволяет ответить на вопрос «сколько стоимости запасов приходится на каждую категорию».

lightspeed_search_products

Полнотекстовый поиск по названию, названию варианта, SKU и handle, с фильтрами по бренду / поставщику / категории / тегу. Сопоставление выполняется локально по кэшированному каталогу, потому что собственный поисковый endpoint API ранжирует плохо, поэтому результаты — точные подстроки.

lightspeed_get_product

Полная информация об одном товаре по ID или точному SKU, включая остатки по каждой торговой точке и вычисленную маржу.

lightspeed_search_customers / lightspeed_get_customer

Поиск клиентов по email (отправляется в API) или по имени, телефону или коду клиента (сопоставляется локально). Возвращает UUID, который инструменты продаж принимают как фильтр customer_id. Это возвращает персональные данные; обращайтесь с ними соответственно.

lightspeed_list_outlets / lightspeed_list_registers / lightspeed_list_accounts

Преобразуют названия магазинов в UUID торговых точек, которые принимают фильтры отчётов, перечисляют POS-терминалы, включая e-commerce регистры, и показывают, какие аккаунты доступны серверу. lightspeed_list_accounts никогда не возвращает токены.

lightspeed_list_reference_data

Один инструмент для работы с brands, suppliers, product_categories, tags, customer_groups, payment_types, promotions, taxes и users. Используйте его, чтобы получить точное написание бренда или категории перед фильтрацией отчёта по нему.

lightspeed_api_get

Запасной выход для любого эндпоинта, для которого нет специализированного инструмента: /consignments, /price_books, /serial_numbers и так далее. Выполняется только GET.

Производительность и ограничения

Форма отчётов определяется тем, что продажи нельзя фильтровать по дате на стороне сервера.

Большую часть холодного вызова составляют ~30 одиночных проб, которые определяют диапазон дат. Эти пробы запоминаются для каждой учётной записи, поэтому для второго отчёта в сессии они обычно не нужны. Сканирования каталога, торговых точек, касс, пользователей и остатков кэшируются на 15 минут.

Чтобы всё работало быстро: передавайте outlet_id, если вас интересует только один магазин, и предпочитайте узкие диапазоны дат. LIGHTSPEED_MAX_SALES (по умолчанию 200 000) ограничивает один вызов, и инструмент прямо сообщает, когда усекает результат, а не молча возвращает частичный ответ.

Одно честное предостережение. Поскольку диапазон дат определяется по версии, продажа, созданная до диапазона, но изменённая после него, может быть пропущена. LIGHTSPEED_SEEK_MARGIN_DAYS (по умолчанию 1) задаёт, насколько раньше диапазона поиск целится, а его увеличение расширяет страховочную сетку ценой сканирования большего числа записей. Это неотъемлемое свойство API, который не фильтрует по дате, а не упрощение, принятое здесь.

Справочник по конфигурации

Разработка

npm run dev      # run from source with tsx
npm run build    # compile to dist/
npm run inspect  # MCP Inspector against the built server
npm run doctor   # credentials + live connectivity check
npm run validate-plugin  # validate the plugin manifests

src/
  index.ts            entry point, env loading, tool registration
  config.ts           account discovery from the environment
  lib/
    client.ts         HTTP client, retry, version pagination
    version-seek.ts   date to version binary search
    sales.ts          sale fetching and metric aggregation
    catalog.ts        cached product, outlet, register, inventory lookups
    time.ts           timezone-aware day boundaries
    format.ts         Markdown table rendering, tool results
  tools/              one file per tool group

Инструменты возвращают таблицы Markdown, а не сырой JSON: модель читает выровненную таблицу надёжнее, чем глубокий JSON-блоб, и при этом тратится лишь малая доля токенов. Исходные числа также доступны в structuredContent для программных вызывающих.

Два соглашения, которых стоит придерживаться, если вы вносите вклад:

• Никогда не выбрасывайте исключения из обработчика инструмента. Ошибки возвращаются как результаты isError. Обёртка guard() обеспечивает это.

• Никогда не используйте console.log. Stdout передаёт JSON-RPC кадры. Диагностика идёт в console.error.

Структура репозитория

.claude-plugin/     plugin + marketplace manifests
.mcp.json           MCP server declaration used by the plugin path
skills/setup/       guided connection walkthrough
skills/reports/     how to answer retail questions with these tools
src/                TypeScript source
dist/               compiled output, committed so plugin installs need no build

dist/ намеренно отслеживается в git, потому что установка плагина Claude Code не выполняет шаг сборки, и скомпилированный сервер должен поставляться вместе с репозиторием. Запустите npm run build перед коммитом изменения исходного кода и одновременно поднимите version в package.json, .claude-plugin/plugin.json и .claude-plugin/marketplace.json при выпуске.

Лицензия

MIT. См. LICENSE.

Не аффилирован с Lightspeed Commerce и не одобрен ею.