be2 MCP (Model Context Protocol)

be2 MCP es un servidor de «capa de gobernanza» interpuesto entre el agente Claude y el backend de productos be2, que permite a los empleados completar tareas por lotes de forma segura mediante lenguaje natural. No es solo un proxy de API, sino una puerta de enlace de seguridad con control de permisos completo, máquina de estados de cambios y mecanismo de auditoría, que garantiza que todas las escrituras al entorno de producción cumplan con los estándares empresariales: sin escrituras a ciegas, sin autoaprobación y con registros de auditoría conservados en toda la cadena.

🟢 Estado actual: Fase 1a–5 completada | 473 pruebas superadas / 0 omitidas | Aceptación de extremo a extremo en vivo SIT be2-220 aprobada

Características principales

• Aprobación manual solo-draft: el agente solo puede crear borradores de change-set; toda escritura requiere aprobación humana a través de un canal independiente (panel o página de confirmación).

• Transferencia de identidad (Identity Pass-through): utiliza el token be2 emitido al iniciar sesión con auth-service; no crea RBAC propio; la decisión de autorización se delega al gateway del backend.

• Dominio modular: cada área de negocio (como publicación/retirada, inventario) se encapsula como un módulo independiente; agregar un nuevo action type no afecta al núcleo.

• Panel de asistente por lotes (Batch Wizard): compatible con la representación de paneles de aprobación interactivos y asistentes de operación en Claude Desktop MCP Apps.

• Auditoría de cadena completa (Append-only Audit): registra el trace de cada paso desde la llamada a la herramienta hasta la ejecución, y nunca almacena tokens en texto plano.

Related MCP server: @vaibot/mcp-server

Arquitectura del sistema

Claude Client (Code/Desktop)
       │
       │ (MCP over Streamable HTTP + OAuth 2.1 不透明參考 token)
       ▼
┌─────────────────────────── be2-mcp server (治理層) ───────────────────────────┐
│                                                                             │
│  [OAuth 2.1 外殼] 負責 Discovery / DCR / PKCE                                │
│        │                                                                    │
│  [Core 治理層]   change-set 狀態機、CAS 防重複、scope-binding、稽核留存      │
│        │                                                                    │
│  [Domain Modules] (src/modules/product/*)                                   │
│    ├─ shelfToggle (上下架)                                                  │
│    ├─ inventorySetting (數量)                                               │
│    ├─ inventoryPlatform (平台切換)                                          │
│    └─ shelfSchedule (排程)                                                  │
│                                                                             │
└─┬───────────────────────────────┬─────────────────────────────────────────┬─┘
  │ (帶 be2 JWT 查改)             │ (帶 service key 換碼/refresh)            │ (互動批准)
  ▼                               ▼                                         ▼
be2 gateway /product/api/v1      auth-service /api/v1/          UI 面板 (mcp-ui) / 確認頁 SSO

Resumen del modelo de seguridad

Inicio rápido

1. Instalar dependencias

   npm install

2. Preparación de variables de entorno Copie .env.example como .env. Nunca complete ni haga commit de tokens o contraseñas reales de producción. Se necesita un SIT_AUTHSVC_SERVICE_KEY de SIT.

3. Iniciar el servidor y compilar la UI

   npm run build:ui
   npm run dev

4. Conexión con Claude (con Claude Code como ejemplo)

   claude mcp add be2-mcp --transport http http://127.0.0.1:8787/mcp

   Al ejecutarlo, se abrirá la página de inicio de sesión SSO de be2-auth en el navegador.

5. Pruebas

   npm run ci

Árbol de estructura del proyecto

src/
 ├─ core/       # 治理層基礎設施 (change-set、CAS、audit、store)
 ├─ oauth/      # OAuth 2.1 外殼 (Discovery, DCR, authorize, token routes)
 ├─ auth/       # 認證內核 (TokenManager、auth-service 介接)
 ├─ server/     # Streamable HTTP server, confirm routes, 路由組裝
 ├─ tools/      # MCP tools 註冊與介面
 ├─ ui/         # 面板與精靈的 isomorphic 前端 (esbuild 打包入口)
 └─ modules/    # Domain modules 實作 (純業務邏輯)
     └─ product/
         ├─ shelfToggle/       # 商品/方案上下架模組
         ├─ inventorySetting/  # 庫存數量修改模組
         ├─ inventoryPlatform/ # 庫存平台切換模組
         └─ shelfSchedule/     # 上下架排程模組

Mapa de documentación

• CLAUDE.md — Reglas de desarrollo y compendio de comandos.

• docs/be2-mcp/design-overview.md — Una lectura para entender la arquitectura MCP y las decisiones clave (lectura obligatoria para Demo / recorrido de arquitectura).

• docs/be2-mcp/demo-guide.md — Guion estándar para demostraciones y demos de funciones.

• docs/be2-mcp/security-model-explainer.md — Explicación del modelo de seguridad en lenguaje sencillo.

• docs/be2-mcp/oauth-runbook.md — Integración OAuth, mecanismo de refresh y explicación de SSO.

• docs/be2-mcp/mcp-apps-runbook.md — Guía de uso del mecanismo de aprobación por panel en Claude Desktop.

• docs/be2-mcp/phase4a-runbook.md — Guía de operación del asistente por lotes (plataforma de inventario/programación).

• docs/be2-mcp/module-catalog.md — Lista de módulos implementados.

• docs/be2-mcp/module-onboarding.md — Lista de verificación para integrar nuevos dominios / action types.