be2 MCP (Model Context Protocol)

be2 MCP — это сервер «уровня управления» (governance layer) между агентом Claude и товарным бэкендом be2, который позволяет сотрудникам безопасно выполнять пакетные задачи на естественном языке. Это не просто API-прокси, а безопасный шлюз с полным контролем прав доступа, машиной состояний изменений и механизмом аудита, гарантирующий, что все записи в производственную среду соответствуют корпоративным стандартам: никаких слепых записей, никакого самоодобрения и полное сохранение аудит-журнала на всём пути.

🟢 Текущий статус: Phase 1a–5 завершён | 473 tests passed / 0 skipped | SIT be2-220 Live — сквозная приёмка пройдена

Ключевые особенности

• draft-only ручное утверждение: агент может только создавать черновики change-set; запись всегда требует ручного одобрения через отдельный канал (панель или страница подтверждения).

• Сквозная идентификация (Identity Pass-through): используется be2 token, выдаваемый при входе через auth-service; собственная RBAC не создаётся, решение об авторизации делегируется бэкенд-gateway.

• Модульные домены: каждый бизнес-домен (например, публикация/снятие с публикации, остатки) инкапсулируется в отдельный module; добавление нового action type не затрагивает core.

• Панель пакетного мастера (Batch Wizard): поддерживает рендеринг интерактивных панелей утверждения и операционных мастеров в Claude Desktop MCP Apps.

• Аудит на всём пути (Append-only Audit): фиксируется trace каждого шага от tool call до выполнения; token в открытом виде никогда не сохраняются.

Related MCP server: @vaibot/mcp-server

Архитектура системы

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

Сводка модели безопасности

Быстрый старт

1. Установка зависимостей

   npm install

2. Подготовка переменных окружения Скопируйте .env.example в .env. Категорически запрещается указывать или коммитить любые реальные token или пароли производственной среды. Потребуется один SIT-ключ SIT_AUTHSVC_SERVICE_KEY.

3. Запуск Server и сборка UI

   npm run build:ui
   npm run dev

4. Подключение Claude (на примере Claude Code)

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

   После выполнения в браузере откроется страница входа be2-auth SSO.

5. Тестирование

   npm run ci

Дерево структуры проекта

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

Карта документов

• CLAUDE.md — железные правила разработки и полный справочник команд.

• docs/be2-mcp/design-overview.md — одна статья, чтобы понять архитектуру MCP и ключевые решения (обязательно к прочтению для Demo / обзора архитектуры).

• docs/be2-mcp/demo-guide.md — стандартный сценарий для презентаций и функционального Demo.

• docs/be2-mcp/security-model-explainer.md — объяснение модели безопасности простым языком.

• docs/be2-mcp/oauth-runbook.md — описание подключения OAuth, механизма refresh и SSO.

• docs/be2-mcp/mcp-apps-runbook.md — руководство по использованию механизма утверждения через панель Claude Desktop.

• docs/be2-mcp/phase4a-runbook.md — руководство по работе с пакетным мастером (платформа остатков/планировщик).

• docs/be2-mcp/module-catalog.md — список реализованных модулей.

• docs/be2-mcp/module-onboarding.md — чек-лист подключения нового domain / action type.