WIBI MCP ゲートウェイ

WIBI API v2 をLLMアシスタント向けツールとして公開する MCP（Model Context Protocol） サーバー。

2つのモードに対応：

エンドユーザー向けガイド（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が有効な場合、メールのコードを求められます。その後、パネルと同じ範囲でキャンペーンと加盟店を選択します（管理者は自分のキャンペーン/加盟店を表示、スーパー管理者はすべてを表示）。

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

• WIBIアプリケーションAPIキー（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 — 動的クライアント登録

• GET /authorize — ログイン画面

• POST /oauth/approve — 多段階ログイン（認証情報 → 任意のOTP → キャンペーン/加盟店セレクター）

• POST /token — code / refreshの交換

• POST|GET|DELETE /mcp — MCP Streamable HTTP（Bearer OAuth）

OAuthログインで使用されるLaravel API：

• 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. ルート全体をコンテナ（127.0.0.1:3939）にプロキシする専用vhostの作成

3. WIBI_PUBLIC_URL=https://mcp.wibi.com.ar に変更してコンテナを再作成

4. vhost wibi.com.ar から一時的なOAuthの ProxyPass（/authorize、/token、/register など）を削除

現在の回避策（テストのみ）： OAuthは既存の商用証明書を使用して https://wibi.com.ar で公開され、OAuthルート + /mcp をコンテナにプロキシしています。最終設計ではありません。

注意事項：

• DCRクライアント + OAuthトークン + WibiSession はRedisに永続化されます（Dockerでは OAUTH_STORE=redis）。MCPトランスポートはプロセスのメモリ内に残ります。

• 現在は単一レプリカ。Redisはマルチレプリカへの道を開きます。recreate後もClaudeの再接続を求めるべきではありません。

• HTTPS必須（認証情報はフォームで送信されるため）。

• ゲートウェイは加盟店のユーザー名/パスワードを決して保存しません。短命のJWT + 不透明なリフレッシュトークンのみ（本番では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と監査用の書き込みログに含まれます。

WIBI JWTの有効期限が近づくと、ゲートウェイは 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を使用）。最初の2つは参照のみ、3つ目は監査用に実際の actor_id を保持したままJWT + refreshを再発行します。直接加盟店（アクターなしのログイン）はこれらのツールを表示できません。

wibi_buscar_campanias が存在する理由： wibi_mis_campanias は、アクティブな加盟店のネットワークに関連付けられたキャンペーン（通常は1つ）のみを返し、管理者の全スコープは返しません。スーパー管理者は何百ものキャンペーンにアクセスできる可能性があり、IDで把握していません。wibi_buscar_campanias を使用すると、ユーザーが事前にidCampaniaを知らなくても、Claudeに「キャンペーンXに切り替えて」と名前で依頼できます。

主なツール

• レポート：取引、顧客、商品、分類子、ブランド、セグメント、タグ、クーポン

• 行動：顧客サマリー、顧客分析

• 配信：タグ、WhatsAppテンプレート、スケジュール/照会

• サブスクリプション：アラートタイプ、作成/照会

• OAuthモード：wibi_mis_campanias

• OAuthモードで、管理者セッションのみ（wibi_mis_campanias の es_admin: true）：wibi_buscar_campanias（idCampaniaを知らなくても、管理者のスコープ内で名前でキャンペーンを検索）、wibi_comercios_de_campania（管理者のスコープ内のキャンペーンの加盟店を一覧表示）、wibi_cambiar_comercio（再ログインなしでセッションのアクティブな加盟店/キャンペーンを変更）

メールテンプレートツールは、対応するLaravelエンドポイントが存在するまで無効化されています。

セキュリティ

• 加盟店ごとの分離：各MCPセッションは、ログインの sessionId OAuth + IdComercio に紐付けられます。

• Laravelでの書き込みは、トークンのスコープに対して顧客/タグ/アラートを検証します。

• /oauth/approve と /mcp でのレート制限。

• Cache-Control: no-store、X-Frame-Options: DENY、ログインページのCSP。