WIBI MCP Gateway

MCP(Model Context Protocol) 서버가 WIBI API v2를 LLM 어시스턴트용 도구로 노출합니다.

두 가지 모드를 지원합니다:

최종 클라이언트(커머스 WIBI) 가이드

개발자일 필요도 없고 JSON 파일을 수정할 필요도 없습니다.

Claude 웹 (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 ID와 비밀번호를 입력하세요:

   • 커머스: 시스템에 있는 해당 커머스의 계정 정보를 그대로 사용 → 바로 접속.

   • 패널 관리자: WIBI 패널 관리자 계정을 사용(커머스 계정 아님). 캠페인에서 2FA가 활성화되어 있으면 이메일로 전송된 코드를 입력합니다. 이후 패널과 동일한 범위의 캠페인과 커머스를 선택합니다 (관리자는 자신의 캠페인/커머스를, 슈퍼 관리자는 전체를 볼 수 있습니다).

6. 승인하세요. 이제 Claude에게 다음과 같은 작업을 요청할 수 있습니다:

   • “내 캠페인의 상품을 목록으로 보여줘”

   • “DNI …인 고객을 찾아줘”

   • “내 캠페인이 무엇인가요?”

각 세션은 선택한 커머스에 대해서만 동작합니다. 공유 토큰이나 클라이언트별 구성이 없습니다.

Claude Desktop

1. Claude Desktop을 열고 Settings → Connectors (버전에 따라 Developers)로 이동하세요.

2. URL https://wibi.com.ar/mcp를 사용해 원격 커넥터를 추가하세요 (임시 주소; 아래 DNS 참고).

3. 브라우저에서 WIBI ID/비밀번호를 입력해 로그인을 완료하세요.

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 — 헬스체크(health check)

• 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)

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. 전용 vhost를 만들어 모든 루트(127.0.0.1:3939)를 컨테이너로 프록시

3. WIBI_PUBLIC_URL=https://mcp.wibi.com.ar로 변경한 뒤 컨테이너를 다시 생성

4. wibi.com.ar vhost에서 OAuth 관련 임시 ProxyPass를 제거(/authorize, /token, /register 등)

현재 임시 우회(테스트 전용): OAuth 는 기존 상용 인증서와 함께 https://wibi.com.ar에 배포되며, OAuth 경로와 /mcp를 컨테이너로 프록시합니다. 최종 설계가 아닙니다.

참고:

• DCR 클라이언트 + OAuth 토큰 + WibiSession은 Redis에 저장됩니다(Docker에서는 OAUTH_STORE=redis). MCP 전송 프로토콜은 여전히 프로세스 메모리에 보관됩니다.

• 현재 단일 레플리카이며, Redis가 멀티 레플리카 확장을 대비해 둔 것입니다. 컨테이너를 다시 만들어도 Claude를 재연결할 필요가 없습니다.

• HTTPS는 필수입니다(아이디/비밀번호가 폼을 통해 전송되므로).

• 게이트웨이는 커머스의 ID/비밀번호를 저장하지 않으며, 짧은 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와 쓰기 로그에 포함되어 감사(audit)에 사용됩니다.

WIBI JWT가 곧 만료되면 게이트웨이는 POST /onzecrm/v2/auth/refresh를 사용해 다시 비밀번호를 요청하지 않고 토큰을 갱신합니다.

한 세션 내 커머스 전환(관리자만): 관리자/슈퍼 관리자는 wibi_buscar_campanies, wibi_comercios_de_campania, wibi_cambiar_comercio 도구를 사용하여 다시 로그인하거나 2FA를 다시 통과하지 않고 다른 커머스로 전환할 수 있습니다(아래 참조). 내부적으로는 POST /onzecrm/v2/auth/my-campanias, POST /onzecrm/v2/auth/my-scoped-comercios, POST /onzecrm/v2/auth/switch-scope를 호출합니다(모두 현재 토큰의 Bearer 사용). 앞의 두 가지는 조회만 하고, 세 번째는 실제 actor_id를 유지한 채 JWT + refresh를 재발급해 감사 로그를 남깁니다. 커머스 직접 로그인(actor 없이) 환경에서는 해당 도구들이 보이지 않습니다.

wibi_buscar_campanias가 존재하는 이유: wibi_misson_campanias는 현재 활성 커머스 네트워크(일반적으로 하나)의 캠페인만 반환하며, 관리자 전체 범위를 반환하지 않습니다. 예를 들어 슈퍼 관리자는 수백 개의 캠페인에 접근 가능할 수 있고 캠페인 ID를 모를 수도 있는데, wibi_buscar_campanias를 통해 사용자가 사전에 idCampania를 알 필요 없이 Claude에게 “캠페인 X로 변경”이라고 이름으로 요청할 수 있습니다.

주요 도구

• 보고서: 거래 내역, 고객, 상품, 분류자(classifier), 브랜드, 세그먼트, 태그, 쿠폰

• 고객 행동: 고객 요약, 고객 분석

• 발송(캠페인): 태그, WhatsApp 템플릿, 예약/조회

• 구독: 알림 유형, 생성/조회

• OAuth 모드: wibi_mis_campanias

• OAuth 모드에서 관리자 세션만(wibi_mis_campanias에 es_admin: true): wib_buscar_campanias(관리자 범위 내에서 캠페인 ID를 몰라도 캠페인/이름으로 검색), wibi_comercios_de_campania(관리자 범위 내 캠페인의 커머스 목록), wibi_cambiar_comercio(재로그인 없이 현재 세션의 커머스/캠페인를 변경)를 제공합니다.

이메일 템플릿 도구는 해당하는 Laravel 엔드포인트가 생길 때까지 비활성화되어 있습니다.

보안

• 커머스 격리: 각 MCP 세션은 OAuth sessionId + 로그인의 IdComercio에 바인딩됩니다.

• Laravel 쓰기 동작은 토큰의 범위(scope)에 따라 고객/태그/알림 등을 검사합니다.

• /oauth/approve 와 /mcp 에도 rate limit이 적용됩니다.

• Cache-Control: no-store, X-Frame-Options: DENY, 로그인 페이지에는 CSP(컨스트) 적용.