be2 MCP (Model Context Protocol)

be2 MCP ist ein „Governance-Layer"-Server zwischen dem Claude-Agenten und dem be2-Produkt-Backend, der es Mitarbeitern ermöglicht, Batch-Aufgaben sicher über natürliche Sprache auszuführen. Es ist nicht nur ein API-Proxy, sondern ein Sicherheits-Gateway mit vollständiger Berechtigungssteuerung, Änderungs-Zustandsmaschine und Audit-Mechanismus, das sicherstellt, dass alle Schreibvorgänge in der Produktion den Unternehmensstandards entsprechen: kein blindes Schreiben, keine Selbstgenehmigung und vollständige Audit-Protokolle über die gesamte Kette.

🟢 Status: Phase 1a–5 abgeschlossen | 473 Tests bestanden / 0 übersprungen | SIT be2-220 Live-End-to-End-Abnahme bestanden

Kernfunktionen

• Nur-Entwurf mit menschlicher Genehmigung: Der Agent kann nur Change-Set-Entwürfe erstellen; alle Schreibvorgänge müssen über einen unabhängigen Kanal (Dashboard oder Bestätigungsseite) menschlich genehmigt werden.

• Identitätsdurchgriff (Identity Pass-through): Verwendet das vom Auth-Service ausgestellte be2-Token; kein eigenes RBAC, die Autorisierungsprüfung wird an das Backend-Gateway delegiert.

• Modularisierte Domänen: Jede Geschäftsdomäne (z. B. Veröffentlichung/Zurückziehung, Bestandsverwaltung) ist als unabhängiges Modul gekapselt; neue Aktionsarten berühren nicht den Kern.

• Batch-Assistent (Batch Wizard): Unterstützt Claude Desktop MCP Apps bei der Darstellung interaktiver Genehmigungs-Panels und Bedienungsassistenten.

• Durchgängige Auditierung (Append-only): Protokolliert jeden Trace vom Tool-Aufruf bis zur Ausführung; speichert niemals Klartext-Tokens.

Related MCP server: @vaibot/mcp-server

Systemarchitektur

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

Sicherheitsmodell-Zusammenfassung

Schnellstart

1. Abhängigkeiten installieren

   npm install

2. Umgebungsvariablen vorbereiten Kopieren Sie .env.example nach .env. Geben Sie niemals echte Produktions-Tokens oder Passwörter ein oder committen Sie diese. Sie benötigen einen SIT-SIT_AUTHSVC_SERVICE_KEY.

3. Server starten & UI erstellen

   npm run build:ui
   npm run dev

4. Claude-Anbindung (am Beispiel Claude Code)

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

   Nach der Ausführung öffnet sich die be2-auth-SSO-Anmeldeseite im Browser.

5. Tests

   npm run ci

Projektstruktur

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/     # 上下架排程模組

Dokumentationsübersicht

• CLAUDE.md — Entwicklungsregeln und Befehlsreferenz.

• docs/be2-mcp/design-overview.md — Architektur und zentrale Entscheidungen auf einen Blick (Demo / Architekturübersicht Pflichtlektüre).

• docs/be2-mcp/demo-guide.md — Standardablauf für Vorführungen und Funktionsdemonstrationen.

• docs/be2-mcp/security-model-explainer.md — Allgemeinverständliche Erklärung des Sicherheitsmodells.

• docs/be2-mcp/oauth-runbook.md — OAuth-Anbindung, Refresh-Mechanismus und SSO-Erläuterung.

• docs/be2-mcp/mcp-apps-runbook.md — Bedienungsanleitung für das Genehmigungs-Panel in Claude Desktop.

• docs/be2-mcp/phase4a-runbook.md — Bedienungsanleitung für den Batch-Assistenten (Bestandsplattform / Planung).

• docs/be2-mcp/module-catalog.md — Katalog der implementierten Module.

• docs/be2-mcp/module-onboarding.md — Checkliste für die Anbindung neuer Domänen / Aktionsarten.