Демо: API управления пользователями + MCP-слои

Небольшое демо на Node.js (только JS). Презентационный пример, показывающий по слоям архитектуру, где один и тот же API предоставляется и человеку-пользователю, и AI-агенту — с раздельной аутентификацией и раздельными областями доступа, а со стороны AI поверх него надет MCP-сервер (слой описания API).

Исходная идея дизайна — боевой MCP из spx-learning-square (spx-learning-square/mcp/, 65 инструментов, распространение через .mcpb). Это демо сводит эту концепцию к минимальной конфигурации.

Общая схема

 人間ユーザー ──ログイン──▶ セッショントークン ─┐
                                                  │ Authorization: Bearer
 AI (Claude) ──▶ MCP サーバー ──PAT──────────────┤
              （mcp/index.mjs                     ▼
                = API 説明層）          ┌─────────────────────────┐
                                        │ API サーバー (Express)  │
                                        │  認証層（2 系統）       │
                                        │  エージェント公開       │
                                        │  レジストリ             │
                                        │  controller             │
                                        │  service                │
                                        │  repository（メモリ）   │
                                        └─────────────────────────┘

Related MCP server: MCP CRUD Tools

Состав слоёв

Матрица прав (суть демо)

Разрушающие операции (обновление и удаление) не регистрируются в реестре и тем самым остаются доступны только человеку. Ключевой момент: «что разрешено AI» видно сразу в одном файле — agentRegistry.mjs.

Как запустить

1. API-сервер

npm install
npm run api          # http://localhost:3000

Запуск в Docker (контейнеризуется только API):

npm run docker       # = docker compose up --build → http://localhost:3000

Слой MCP (mcp/index.mjs) в контейнер не помещается. Поскольку Claude Desktop / Claude Code запускают его как stdio-процесс на машине пользователя, распространение идёт не через Docker, а через .mcpb. Это тоже пункт для презентации: API — на стороне сервера (Docker/ECS), MCP — на стороне клиента (.mcpb), и единицы развёртывания разделены.

Поток человека-пользователя (вход → CRUD):

# ログイン（デモ: alice / demo）
TOKEN=$(curl -s -X POST localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"login_id":"alice","password":"demo"}' | node -p 'JSON.parse(require("fs").readFileSync(0)).data.token')

curl -s localhost:3000/api/users -H "Authorization: Bearer $TOKEN"          # 一覧
curl -s -X DELETE localhost:3000/api/users/3 -H "Authorization: Bearer $TOKEN"  # 削除も OK

Поток AI-агента (PAT, ключ по умолчанию agent-demo-key):

curl -s localhost:3000/api/users -H "Authorization: Bearer agent-demo-key"       # ✅ 200
curl -s localhost:3000/api/agent/apis -H "Authorization: Bearer agent-demo-key"  # ✅ 公開一覧
curl -s -X DELETE localhost:3000/api/users/2 \
  -H "Authorization: Bearer agent-demo-key"                                       # ❌ 403 user_only

Есть два вида кодов ошибок: user_only — API с гвардом «только для человека» (обновление, удаление), agent_not_allowed — гвард forAgent есть, но API не зарегистрирован в реестре.

2. MCP-сервер (слой описания API)

Отладочный UI (MCP Inspector):

npm run inspect

Регистрация в Claude Code:

claude mcp add users-demo -- node /Users/d.bui/Documents/project/mcp-from-scratch/mcp/index.mjs

Примеры диалога: «покажи список пользователей» → list_users, «зарегистрируй нового участника» → create_user, «удали номер 3» → инструмента нет, поэтому направляем в админ-панель (задано в instructions).

3. E2E-тест (стучим в MCP «вместо Claude»)

npm test             # test/mcp-client.test.mjs

Клиент MCP SDK подключается по stdio к mcp/index.mjs (тем же путём, что и Claude), затем: запуск API → автоматическая проверка всех инструментов + ресурсов + аномальных случаев (несуществующий ID / дубликат email / нарушение схемы). Годится и для живого демо на презентации.

4. Распространение через .mcpb для Claude Desktop

.mcpb = Desktop Extension: manifest.json + код, упакованные в zip. Устанавливается двойным кликом, пользователю не нужно ни ставить Node, ни редактировать файлы конфигурации. URL API и ключ доступа инжектятся в env из user_config (форма при установке) (ключи с sensitive: true сохраняются в связку ключей ОС).

npx @anthropic-ai/mcpb validate manifest.json
npm run pack         # → dist/users-mcp-demo.mcpb（node_modules ごと同梱）

Результат сборки выводится в dist/ (вне git). Благодаря .mcpbignore код API и файлы, связанные с Docker, в расширение не попадают — в бандл входят только manifest.json + mcp/ + node_modules.

Слайды для презентации

Откройте slides/index.html в браузере — можно сразу выступать (навигация стрелками ← →, 14 слайдов, работает офлайн). Структура: общая схема → код-шоты каждого слоя → матрица прав → распространение → порядок демо → выводы из боевой эксплуатации.

Пункты для презентации (из боевой эксплуатации spx-learning-square)

• Слой MCP не имеет прав. Он не касается БД, а только вызывает REST API по PAT. Проверка прав и валидация — всё в одном месте, на стороне API: даже если MCP сломается, инцидентов, невозможных через UI, не произойдёт.

• Аутентификация разделена на две линии. Человек = вход + сессия, AI = предварительно выданный PAT. Разное происхождение токенов позволяет проектировать отзыв, аудит и ограничение частоты запросов по отдельности.

• Открытие для AI — только явной регистрацией. Если открывать по префиксу пути, можно случайно открыть и соседний чувствительный API (это реальный урок, который едва не случился). Реестр при этом работает и как «спецификация API для AI».

• Описания инструментов — это инструкции для модели. Операционные правила вроде «не угадывай ID, получай через list_users» или «при удалении направляй в админ-панель» пишутся в description / instructions, и поведение AI управляется текстом, а не кодом.

• Ошибки возвращаются не через throw, а через isError + машиночитаемый code. Модель читает code и может восстановиться сама (email_taken → предложить другой вариант и т.п.).

• stdout — только для JSON-RPC. В stdio-сервере console.log ломает коммуникацию. Логи — обязательно через console.error.

Ссылки

• Спецификация и документация MCP: https://modelcontextprotocol.io

• TypeScript/JS SDK: https://github.com/modelcontextprotocol/typescript-sdk

• MCPB (спецификация manifest + CLI): https://github.com/anthropics/mcpb

• Боевая реализация: ../spx-learning-square/mcp/ (esbuild-сборка в один файл, вшитые метки окружения, backend динамически генерирует .mcpb)