WIBI MCP Gateway

Server MCP (Model Context Protocol), der die WIBI-API v2 als Werkzeuge für LLM-Assistenten bereitstellt.

Unterstützt zwei Modi:

Leitfaden für den Endkunden (WIBI-Händler)

Sie müssen kein Entwickler sein und keine JSON-Dateien bearbeiten.

Claude Web (claude.ai)

1. Melden Sie sich bei claude.ai mit Ihrem Konto an.

2. Gehen Sie zu Settings → Connectors → Add custom connector.

3. Fügen Sie die Server-URL ein: https://wibi.com.ar/mcp (temporäre Test-URL; siehe DNS-Hinweis unten).

4. Claude öffnet den WIBI-Login-Bildschirm im Browser.

5. Geben Sie Benutzername und Passwort von WIBI ein:

   • Händler: dieselben Daten wie der Händler im System → direkter Zugriff.

   • Panel-Admin: Benutzer des WIBI-Panels (nicht der des Händlers). Wenn die Kampagne 2FA aktiviert hat, wird der Code aus der E-Mail abgefragt. Danach wählen Sie Kampagne und Händler mit demselben Umfang wie im Panel (Admin sieht seine Kampagnen/Händler; Superadmin sieht alle).

6. Autorisieren Sie. Sie können Claude nun Dinge wie folgende bitten:

   • „Liste die Produkte meiner Kampagne auf“

   • „Suche den Kunden mit der ID …“

   • „Welche Kampagnen habe ich?“

Jede Sitzung arbeitet nur auf dem gewählten Händler. Es gibt keine gemeinsamen Tokens oder Konfiguration pro Kunde.

Claude Desktop

1. Öffnen Sie Claude Desktop → Settings → Connectors (oder Developers, je nach Version).

2. Fügen Sie einen Remote-Connector mit der URL https://wibi.com.ar/mcp hinzu (temporär; siehe DNS-Hinweis).

3. Schließen Sie den Login im Browser mit Ihrem WIBI-Benutzer/Passwort ab.

Related MCP server: meta-ads-mcp

Technischer Leitfaden (internes Team)

Voraussetzungen

• Node.js >= 18

• API-Key der WIBI-Anwendung (approl 1 oder 3)

• API v2 bereitgestellt (enthält /onzecrm/v2/auth/* und /onzecrm/v2/campanias)

Installation

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

stdio-Modus (lokal)

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

Beispiel mcp.json (nur für lokale Entwicklung):

{
  "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-Modus (Produktion)

Mindestvariablen:

In diesem Modus nicht WIBI_USER, WIBI_PASS oder MCP_HTTP_TOKEN konfigurieren: Der Login ist interaktiv (Händler oder Panel-Admin).

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

Endpunkte:

• GET /healthz — Healthcheck

• GET /.well-known/oauth-authorization-server — OAuth-Metadaten

• POST /register — Dynamic Client Registration

• GET /authorize — Login-Bildschirm

• POST /oauth/approve — mehrstufiger Login (Anmeldedaten → optionales OTP → Kampagnen-/Händlerauswahl)

• POST /token — tauscht Code / Refresh

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

Laravel-API, die vom OAuth-Login verwendet wird:

• 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 / Zertifikat

Erforderliche Aktion (wer DonWeb-Zugriff hat): DNS-Eintrag erstellen:

Wenn das DNS existiert, kann ich:

1. Let's-Encrypt-Zertifikat ausstellen (certbot --apache -d mcp.wibi.com.ar)

2. Dedizierten vhost erstellen, der die gesamte Wurzel an den Container proxyt (127.0.0.1:3939)

3. WIBI_PUBLIC_URL=https://mcp.wibi.com.ar ändern und den Container neu erstellen

4. Aus dem vhost wibi.com.ar die temporären OAuth-ProxyPass-Einträge (/authorize, /token, /register usw.) entfernen

Aktueller Workaround (nur Test): OAuth wird auf https://wibi.com.ar mit dem vorhandenen kommerziellen Zertifikat veröffentlicht, wobei OAuth-Routen + /mcp an den Container proxyt werden. Das ist nicht das endgültige Design.

Hinweise:

• DCR-Clients + OAuth-Tokens + WibiSession werden in Redis persistiert (OAUTH_STORE=redis in Docker). Die MCP-Transports bleiben im Prozessspeicher.

• Derzeit eine einzige Replik; Redis lässt die Tür für Multi-Replik offen. Ein Recreate sollte kein erneutes Verbinden von Claude mehr erfordern.

• HTTPS ist Pflicht (die Anmeldedaten werden über das Formular übertragen).

• Das Gateway speichert niemals Benutzer/Passwort des Händlers; nur kurzes JWT + undurchsichtiges Refresh-Token (in Redis in Produktion).

Sitzungsarchitektur

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)

Wenn ein Panel-Admin sich anmeldet, gehört das endgültige JWT weiterhin dem ausgewählten Händler (gleicher v2-Umfang). Der tatsächliche Akteur (actor_id / actor_name / actor_role) reist im JWT und in den Schreib-Logs für die Auditierung.

Wenn das WIBI-JWT kurz vor dem Ablauf steht, erneuert das Gateway es mit POST /onzecrm/v2/auth/refresh (ohne erneute Abfrage des Passworts).

Händlerwechsel innerhalb derselben Sitzung (nur Admins): Ein Admin/Superadmin kann ohne erneutes Login oder erneutes 2FA von einem Händler zu einem anderen wechseln, mithilfe der Tools wibi_buscar_campanias, wibi_comercios_de_campania und wibi_cambiar_comercio (siehe unten). Intern rufen sie POST /onzecrm/v2/auth/my-campanias, POST /onzecrm/v2/auth/my-scoped-comercios und POST /onzecrm/v2/auth/switch-scope auf (alle mit Bearer des aktuellen Tokens); die ersten beiden fragen nur ab, das dritte gibt JWT + Refresh neu aus und bewahrt die tatsächliche actor_id für die Auditierung. Der direkte Händler (Login ohne Akteur) sieht diese Tools nicht.

Warum es wibi_buscar_campanias gibt: wibi_mis_campanias gibt nur die Kampagne zurück, die mit dem Netzwerk des aktiven Händlers verbunden ist (normalerweise eine einzige), nicht den gesamten Umfang des Admins. Ein Superadmin kann Zugriff auf Hunderte von Kampagnen haben und kennt sie nicht per ID. wibi_buscar_campanias ermöglicht es, Claude zu bitten „Wechsle zu Kampagne X“ per Name, ohne dass der Benutzer die idCampania im Voraus kennen muss.

Hauptwerkzeuge

• Berichte: Bewegungen, Kunden, Produkte, Klassifikatoren, Marken, Segmente, Tags, Gutscheine

• Verhalten: Kundenübersicht, Kundenanalyse

• Verteilungen: Tags, WhatsApp-Vorlagen, planen/abfragen

• Abonnements: Alarmtypen, erstellen/abfragen

• Im OAuth-Modus: wibi_mis_campanias

• Im OAuth-Modus, nur für Admin-Sitzungen (es_admin: true in wibi_mis_campanias): wibi_buscar_campanias (sucht Kampagnen per Name innerhalb des Admin-Umfangs, ohne die idCampania zu kennen), wibi_comercios_de_campania (listet Händler einer Kampagne innerhalb des Admin-Umfangs) und wibi_cambiar_comercio (ändert den aktiven Händler/die aktive Kampagne der Sitzung ohne erneutes Login)

Das E-Mail-Vorlagen-Tool ist deaktiviert, bis der entsprechende Laravel-Endpunkt existiert.

Sicherheit

• Isolierung pro Händler: Jede MCP-Sitzung ist an die OAuth-sessionId + IdComercio des Logins gebunden.

• Schreibvorgänge in Laravel validieren Kunden/Tags/Alarme gegen den Umfang des Tokens.

• Rate-Limit auf /oauth/approve und /mcp.

• Cache-Control: no-store, X-Frame-Options: DENY, CSP auf der Login-Seite.