ustore-backoffice-mcp

MCP-сервер для REST API XMPie uStore BackOffice по адресу https://produproduce.mysite.com/ustorebackofficerestapi.

Статус: рабочий, проверен от начала до конца на живом API. Спецификация загружается (52 пути / 63 операции в 15 группах тегов), вход выполняется успешно, и ustore_call_endpoint GET /v1/admin/stores возвращает HTTP 200. Защита от записи корректно отклоняет DELETE.

Дизайн

Сервер не зашивает эндпоинты в код. При первом использовании он загружает собственный документ OpenAPI 3.0 API и предоставляет на его основе пять инструментов:

Это та же схема, что и у MCP-серверов MSSQL (list_databases → list_tables → describe_table → query), и она сохраняет количество инструментов небольшим независимо от того, сколько эндпоинтов предоставляет API. Она также переживает обновления uStore — новые эндпоинты появляются автоматически при следующем обновлении спецификации.

Запись отключена по умолчанию. Методы, отличные от GET, отклоняются, пока на серверном процессе не установлено USTORE_ALLOW_WRITES=true.

Related MCP server: mcp-db-server

Установка

Должен работать на хосте с доступом к внутренней сети produproduce.

cd /opt/mcp/ustore-backoffice-mcp
npm install
cp .env.example .env
$EDITOR .env          # credentials — the base URL and spec URL are preset
npm run probe         # optional: re-confirm the spec URL and auth handshake

Рукопожатие аутентификации подтверждено на живом API и уже используется по умолчанию:

POST {base}/v1/admin/auth/login   {"email": "...", "password": "..."}
  -> 200 {"Token": "..."}

Authorization: uStoreBackoffice <token>     # on every subsequent request

Обратите внимание: в теле входа используется email, а не username, а поле токена — с заглавной Token. Схема буквально uStoreBackoffice — API отклоняет любой другой префикс с {"Errors":[{"Message":"Invalid security token."}]}.

URL спецификации также подтверждён и задан заранее:

USTORE_SPEC_URL=https://produproduce.mysite.com/ustorebackofficerestapi/ustore-oas3

Его необходимо задать явно — этот деплоймент отдаёт OAS3 по адресу /ustore-oas3, а пути, которые loadSpec() в противном случае опрашивала бы, все возвращают 404.

Затем:

npm run http          # or: npm run stdio

Проверка:

$ curl -s localhost:8931/healthz
{"ok":true,"target":"https://produproduce.mysite.com/ustorebackofficerestapi"}

/healthz доказывает только то, что процесс запущен. Чтобы подтвердить, что часть API работает, вызовите ustore_server_info из клиента — он сообщает выбранную схему аутентификации и количество операций и громко падает, если вход не работает.

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

pm2

pm2 start index.js --name ustore-mcp --node-args="--enable-source-maps"
pm2 save

systemd

[Unit]
Description=uStore BackOffice MCP server
After=network-online.target

[Service]
Type=simple
User=tc
WorkingDirectory=/opt/mcp/ustore-backoffice-mcp
EnvironmentFile=/opt/mcp/ustore-backoffice-mcp/.env
ExecStart=/usr/bin/node index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Держите .env с правами chmod 600 — в нём хранятся учётные данные uStore BackOffice, которые являются административными.

HAProxy

Для SSE требуется отключить буферизацию и установить длинный тайм-аут сервера, иначе сеансы обрываются:

backend be_mcp_ustore
    mode http
    option http-server-close
    timeout server 3600s
    timeout tunnel 3600s
    http-request set-header X-Accel-Buffering no
    server ustore1 127.0.0.1:8931 check

Обслуживаются оба транспорта: POST /mcp (Streamable HTTP, текущая спецификация) и GET /sse + POST /messages (унаследованный SSE, совместимый с существующим стеком). Установите MCP_BEARER_TOKEN, если хотите, чтобы сам сервер проверял общий секрет, а не полагался только на ACL HAProxy.

Конфигурация клиента

Локальный stdio (Claude Desktop на той же машине):

{
  "mcpServers": {
    "ustore-backoffice": {
      "command": "node",
      "args": ["/opt/mcp/ustore-backoffice-mcp/index.js"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

Записывайте файл конфигурации в UTF-8 без BOM.

В этом блоке env учётные данные не нужны: сервер читает .env, который находится рядом с index.js. Claude Desktop запускает MCP-серверы с cwd=/ и почти пустым окружением, поэтому config.js ищет .env относительно собственного расположения файла, а не рабочего каталога. Всё, что вы действительно поместите в env, по-прежнему имеет приоритет — реальные переменные окружения имеют приоритет над файлом.

После редактирования конфигурации полностью завершите Claude Desktop (Cmd-Q на macOS, а не просто закройте окно), чтобы процесс сервера был перезапущен.

Примечания и подводные камни

• Область действия учётных данных. Учётные записи BackOffice API обычно имеют полные права администратора. Если uStore поддерживает ограниченную роль оператора, используйте её — защита от записи в этом сервере защищает от случайностей, а не от скомпрометированного токена.

• USTORE_ALLOW_PATHS — это список разрешений через регулярное выражение. Его установка сужает сервер до контроллеров, которые вам действительно нужны, что является более сильным контролем, чем один только флаг записи.

• Усечение ответа по умолчанию составляет 60 тысяч символов. Если конечная точка списка переполняется, используйте её параметры постраничной навигации, а не увеличивайте лимит — в этом API они называются pageNumber (с 1) и pageSize (по умолчанию 50).

• Кэширование спецификации обновляется каждые 15 минут. После обновления uStore вызовите ustore_server_info с refreshSpec: true, чтобы сразу получить изменения.

• Сбои аутентификации, которые выглядят как сбои соединения. Сервер запускается и перечисляет свои инструменты, даже если учётные данные отсутствуют — вход происходит только при первом вызове API. Если инструменты появляются, но каждый вызов завершается ошибкой, запустите ustore_server_info и проверьте hasToken.

• Это дополняет, а не заменяет SQL MCP-сервер. REST API обеспечивает соблюдение бизнес-логики uStore, поэтому это правильный путь для всего, что изменяет состояние. Прямые запросы [PRODUPRODUCE].ustore остаются лучшими для отчётных объединений и археологии схемы.