WIBI MCP Gateway

Сервер MCP (Model Context Protocol), который предоставляет API v2 WIBI в виде инструментов для LLM-ассистентов.

Поддерживает два режима:

Руководство для конечного клиента (торговец WIBI)

Не нужно быть разработчиком или редактировать JSON-файлы.

Claude web (claude.ai)

1. Зайдите на claude.ai со своей учетной записью.

2. Перейдите в Settings → Connectors → Add custom connector.

3. Вставьте URL сервера: https://wibi.com.ar/mcp (временный тестовый URL; см. примечание о DNS ниже).

4. Claude откроет экран входа WIBI в браузере.

5. Введите пользователя и пароль WIBI:

   • Торговец: те же данные торговца в системе → прямой доступ.

   • Админ панели: пользователь панели WIBI (не торговца). Если в кампании включен 2FA, потребуется код из email. Затем вы выбираете кампанию и торговца с тем же охватом, что и в панели (админ видит свои кампании/торговцев; суперадмин видит все).

6. Авторизуйтесь. Теперь вы можете просить Claude о таких вещах, как:

   • «Перечисли продукты моей кампании»

   • «Найди клиента с DNI …»

   • «Какие у меня кампании?»

Каждая сессия работает только с выбранным торговцем. Нет общих токенов или конфигурации на клиента.

Claude Desktop

1. Откройте Claude Desktop → Settings → Connectors (или Developers, в зависимости от версии).

2. Добавьте удаленный коннектор с URL https://wibi.com.ar/mcp (временный; см. примечание о DNS).

3. Завершите вход в браузере с вашим логином/паролем WIBI.

Related MCP server: meta-ads-mcp

Техническое руководство (внутренняя команда)

Требования

• Node.js >= 18

• API-ключ приложения WIBI (approl 1 или 3)

• Развернутое API v2 (включая /onzecrm/v2/auth/* и /onzecrm/v2/campanias)

Установка

cd wibi-mcp-gateway
npm install --ignore-scripts
npm run build

Режим stdio (локально)

export WIBI_BASE_URL=https://apiv2.wibi.com.ar
export WIBI_API_KEY=...
export WIBI_USER=...
export WIBI_PASS=...
# opcional:
# export WIBI_DEFAULT_CAMPANIA=13793
node dist/index.js

Пример mcp.json (только для локальной разработки):

{
  "mcpServers": {
    "wibi-local": {
      "command": "node",
      "args": ["/ruta/a/wibi-mcp-gateway/dist/index.js"],
      "env": {
        "WIBI_BASE_URL": "https://apiv2.wibi.com.ar",
        "WIBI_API_KEY": "...",
        "WIBI_USER": "...",
        "WIBI_PASS": "..."
      }
    }
  }
}

Режим HTTP + OAuth (продакшн)

Минимальные переменные:

Не настраивайте WIBI_USER, WIBI_PASS или MCP_HTTP_TOKEN в этом режиме: вход интерактивный (торговец или админ панели).

MCP_TRANSPORT=http \
WIBI_BASE_URL=https://apiv2.wibi.com.ar \
WIBI_API_KEY=... \
WIBI_PUBLIC_URL=https://wibi.com.ar \
node dist/index.js --http

Эндпоинты:

• GET /healthz — проверка здоровья

• GET /.well-known/oauth-authorization-server — метаданные OAuth

• POST /register — Dynamic Client Registration

• GET /authorize — экран входа

• POST /oauth/approve — многошаговый вход (учетные данные → опциональный OTP → выбор кампании/торговца)

• POST /token — обмен code / refresh

• POST|GET|DELETE /mcp — MCP Streamable HTTP (Bearer OAuth)

API Laravel, используемое для входа OAuth:

• POST /onzecrm/v2/auth/login

• POST /onzecrm/v2/auth/verify-otp / resend-otp

• POST /onzecrm/v2/auth/scoped-comercios / select-scope

• POST /onzecrm/v2/auth/refresh / revoke

Docker

cp .env.example .env   # completar WIBI_BASE_URL, WIBI_API_KEY, WIBI_PUBLIC_URL
docker compose up -d --build
curl http://127.0.0.1:3939/healthz

DNS / сертификат

Требуемое действие (для тех, у кого есть доступ к DonWeb): создать DNS-запись:

Когда DNS будет существовать, я смогу:

1. Выпустить сертификат Let's Encrypt (certbot --apache -d mcp.wibi.com.ar)

2. Создать выделенный vhost, который проксирует весь корень на контейнер (127.0.0.1:3939)

3. Изменить WIBI_PUBLIC_URL=https://mcp.wibi.com.ar и пересоздать контейнер

4. Удалить из vhost wibi.com.ar временные ProxyPass для OAuth (/authorize, /token, /register и т.д.)

Текущий обходной путь (только для теста): OAuth публикуется на https://wibi.com.ar с существующим коммерческим сертификатом, проксируя маршруты OAuth + /mcp на контейнер. Это не финальный дизайн.

Примечания:

• DCR-клиенты + OAuth-токены + WibiSession сохраняются в Redis (OAUTH_STORE=redis в Docker). MCP-транспорты остаются в памяти процесса.

• Сейчас одна реплика; Redis оставляет дверь открытой для мульти-реплики. После recreate не должно потребоваться переподключение Claude.

• HTTPS обязателен (учетные данные передаются через форму).

• Шлюз никогда не хранит логин/пароль торговца; только короткий JWT + непрозрачный refresh-токен (в Redis в продакшене).

Архитектура сессии

claude.ai → OAuth (login comercio o admin) → access token MCP
         → /mcp (Bearer) → WibiClient con JWT del comercio
         → API v2 Laravel (scope por IdComercio / IdRed / idCampania)

Если входит админ панели, итоговый JWT остается от выбранного торговца (тот же охват v2). Реальный субъект (actor_id / actor_name / actor_role) передается в JWT и в журналах записи для аудита.

Когда JWT WIBI близок к истечению, шлюз обновляет его через POST /onzecrm/v2/auth/refresh (без повторного запроса пароля).

Смена торговца в рамках одной сессии (только для админов): админ/суперадмин может переключаться с одного торговца на другого без повторного входа или повторного прохождения 2FA, используя инструменты wibi_buscar_campanias, wibi_comercios_de_campania и wibi_cambiar_comercio (см. ниже). Внутри они вызывают POST /onzecrm/v2/auth/my-campanias, POST /onzecrm/v2/auth/my-scoped-comercios и POST /onzecrm/v2/auth/switch-scope (все с Bearer текущего токена); первые два только запрашивают, третий перевыпускает JWT + refresh, сохраняя реальный actor_id для аудита. Прямой торговец (вход без субъекта) не видит эти инструменты.

Почему существует wibi_buscar_campanias: wibi_mis_campanias возвращает только кампанию, связанную с сетью активного торговца (обычно одну), а не весь охват админа. Суперадмин может иметь доступ к сотням кампаний и не знать их по ID. wibi_buscar_campanias позволяет попросить Claude «переключись на кампанию X» по имени, без необходимости знать idCampania заранее.

Основные инструменты

• Отчеты: движения, клиенты, продукты, классификаторы, бренды, сегменты, теги, купоны

• Поведение: сводка по клиенту, анализ клиентов

• Рассылки: теги, шаблоны WhatsApp, планирование/просмотр

• Подписки: типы оповещений, создание/просмотр

• В режиме OAuth: wibi_mis_campanias

• В режиме OAuth, только для админ-сессий (es_admin: true в wibi_mis_campanias): wibi_buscar_campanias (поиск кампаний по имени в пределах охвата админа, без необходимости знать idCampania), wibi_comercios_de_campania (список торговцев кампании в пределах охвата админа) и wibi_cambiar_comercio (смена активного торговца/кампании сессии без повторного входа)

Инструмент шаблона email отключен, пока не появится соответствующий эндпоинт Laravel.

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

• Изоляция по торговцу: каждая MCP-сессия привязана к sessionId OAuth + IdComercio входа.

• Записи в Laravel проверяют клиентов/теги/оповещения на соответствие охвату токена.

• Rate limit на /oauth/approve и /mcp.

• Cache-Control: no-store, X-Frame-Options: DENY, CSP на странице входа.