be2 MCP (Model Context Protocol)

be2 MCP is a "governance layer" server that sits between the Claude agent and the be2 product backend, letting employees safely complete batch tasks through natural language. It is not just an API proxy, but a security gateway with full permission control, a change state machine, and an audit mechanism, ensuring that all writes to the production environment meet enterprise standards: no blind writes, no self-approval, and audit records retained across the entire chain.

🟢 Status: Phase 1a–5 complete | 473 tests passed / 0 skipped | SIT be2-220 Live end-to-end acceptance passed

Core Features

• draft-only manual approval: the agent can only create change-set drafts; all writes must be manually approved through an independent channel (panel or confirmation page).

• Identity Pass-through: uses the be2 token issued at auth-service login, does not build its own RBAC, and delegates authorization decisions to the backend gateway.

• Modular domains: each business domain (such as listing/unlisting, inventory) is encapsulated as an independent module; adding an action type does not touch the core.

• Batch Wizard panel: supports Claude Desktop MCP Apps rendering interactive approval panels and operation wizards.

• Append-only Audit: records a trace of every step from tool call to execution, and never stores plaintext tokens.

Related MCP server: @vaibot/mcp-server

System Architecture

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

Security Model Summary

Quick Start

1. Install dependencies

   npm install

2. Prepare environment variables Copy .env.example to .env. Never fill in or commit any real production token or password. You will need a SIT SIT_AUTHSVC_SERVICE_KEY.

3. Start the server & build the UI

   npm run build:ui
   npm run dev

4. Connect Claude (using Claude Code as an example)

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

   After running, the be2-auth SSO login page will pop up in the browser.

5. Testing

   npm run ci

Project Structure Tree

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

Documentation Map

• CLAUDE.md — Development rules and command reference.

• docs/be2-mcp/design-overview.md — Understand the MCP architecture and key decisions in one read (a must-read for demos / architecture tours).

• docs/be2-mcp/demo-guide.md — Standard script for presentations and feature demos.

• docs/be2-mcp/security-model-explainer.md — Plain-language explanation of the security model.

• docs/be2-mcp/oauth-runbook.md — OAuth integration, refresh mechanism, and SSO explanation.

• docs/be2-mcp/mcp-apps-runbook.md — Guide to using the Claude Desktop panel approval mechanism.

• docs/be2-mcp/phase4a-runbook.md — Batch Wizard (inventory platform/scheduling) operation guide.

• docs/be2-mcp/module-catalog.md — List of implemented modules.

• docs/be2-mcp/module-onboarding.md — Checklist for onboarding a new domain / action type.