Demo mit mehrschichtigem Benutzerverwaltungs-API + MCP

Eine kleine Demo, erstellt mit Node.js (nur JS). Ein Präsentationsbeispiel, das Schicht für Schicht zeigt, wie „dasselbe API menschlichen Benutzern und KI-Agenten mit getrennter Authentifizierung und getrennten Freigabebereichen bereitgestellt wird und auf der KI-Seite ein MCP-Server (API-Beschreibungsschicht) darübergelegt wird".

Die Designvorlage stammt vom produktiven MCP von spx-learning-square (spx-learning-square/mcp/, 65 Tools, .mcpb-Verteilung). Diese Demo reduziert diesen Ansatz auf eine minimale Konfiguration.

Gesamtbild

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

Related MCP server: MCP CRUD Tools

Schichtenaufbau

Berechtigungsmatrix (Kern der Demo)

Destruktive Operationen (Aktualisieren, Löschen) werden durch Nicht-Registrierung im Register zu menschenexklusiv. Der Punkt ist, dass „was der KI erlaubt ist" in einer einzigen Datei, agentRegistry.mjs, einsehbar ist.

So führt man es aus

1. API-Server

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

Für den Start mit Docker (nur das API wird containerisiert):

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

Die MCP-Schicht (mcp/index.mjs) wird nicht in den Container aufgenommen. Da es sich um einen Prozess handelt, den Claude Desktop / Claude Code per stdio auf dem Rechner des Benutzers startet, erfolgt die Verteilung nicht über Docker, sondern über .mcpb. Auch das ist ein Präsentationspunkt: API auf der Serverseite (Docker/ECS), MCP auf der Clientseite (.mcpb) – die Deployment-Einheiten sind getrennt.

Ablauf für menschliche Benutzer (Login → 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

Ablauf für KI-Agenten (PAT, Standard-Schlüssel 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

Es gibt zwei Arten von Fehlercodes: user_only = API mit menschenexklusivem Guard (Aktualisieren, Löschen), agent_not_allowed = Guard ist forAgent, aber API nicht im Register.

2. MCP-Server (API-Beschreibungsschicht)

Debug-UI (MCP Inspector):

npm run inspect

Bei Claude Code registrieren:

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

Gesprächsbeispiele: „Zeig mir die Benutzerliste" → list_users, „Registriere ein neues Mitglied" → create_user, „Lösche Nummer 3" → Es gibt kein Tool, daher wird auf den Admin-Bildschirm verwiesen (in instructions angegeben).

3. E2E-Test (MCP als „Claude-Ersatz" aufrufen)

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

Mit dem Client des MCP SDK wird eine stdio-Verbindung zu mcp/index.mjs hergestellt (gleicher Pfad wie Claude), API-Start → automatische Validierung aller Tools + Ressourcen + Fehlerfälle (nicht vorhandene ID / E-Mail-Duplikat / Schemaverstoß). Auch für Live-Demos bei Präsentationen geeignet.

4. Verteilung als .mcpb für Claude Desktop

.mcpb = Desktop-Erweiterung, die manifest.json + Code als zip enthält. Per Doppelklick installierbar; Benutzer müssen weder Node installieren noch Konfigurationsdateien bearbeiten. API-URL und Zugriffsschlüssel werden über user_config (Formular bei der Installation) in die env injiziert (Schlüssel mit sensitive: true werden im OS-Schlüsselbund gespeichert).

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

Die Build-Artefakte werden in dist/ ausgegeben (nicht in der Git-Verwaltung). Durch .mcpbignore werden API-Code und Docker-bezogene Dateien nicht in die Erweiterung aufgenommen – im Bundle sind nur manifest.json + mcp/ + node_modules enthalten.

Präsentationsfolien

slides/index.html im Browser öffnen und direkt präsentieren (Navigation mit ← → Tasten, 14 Folien, offline-fähig). Aufbau: Gesamtbild → Code-Shots der einzelnen Schichten → Berechtigungsmatrix → Verteilung → Demo-Ablauf → Erkenntnisse aus dem Produktivbetrieb.

Präsentationspunkte (aus dem Produktivbetrieb von spx-learning-square)

• Die MCP-Schicht hat keine Berechtigungen. Sie greift nicht auf die DB zu, sondern ruft nur die REST-API mit PAT auf. Berechtigungsprüfung und Validierung erfolgen ausschließlich an einer Stelle auf der API-Seite – selbst wenn MCP kaputtgeht, kann kein Unfall passieren, den die UI nicht verursachen kann.

• Authentifizierung ist in 2 Systeme getrennt. Mensch = Login + Session, KI = vorab ausgestelltes PAT. Wenn die Herkunft der Tokens unterschiedlich ist, können Widerruf, Audit und Ratenbegrenzung ebenfalls getrennt gestaltet werden.

• Die Freigabe für KI erfolgt über ein „explizites Registrierungssystem". Wenn man über Pfad-Präfixe freigibt, kann es zu Unfällen kommen, bei denen versehentlich auch benachbarte sensible APIs geöffnet werden (eine Lehre, die beinahe real passiert wäre). Das Register funktioniert zugleich als „API-Spezifikation für KI".

• Die Tool-Beschreibungen sind Anweisungen an das Modell. Durch das Schreiben von Betriebsregeln wie „IDs nicht raten, sondern mit list_users auflösen" oder „bei Löschung auf den Admin-Bildschirm verweisen" in description / instructions lässt sich das KI-Verhalten nicht über Code, sondern über Text steuern.

• Fehler werden nicht geworfen, sondern mit isError + maschinenlesbarem code zurückgegeben. Das Modell kann den code lesen und selbstständig wiederherstellen (email_taken → Alternativvorschlag machen usw.).

• stdout ist ausschließlich für JSON-RPC. Bei einem stdio-Server zerstört console.log die Kommunikation. Logging erfolgt immer über console.error.

Referenzen

• MCP-Spezifikation und Dokumentation: https://modelcontextprotocol.io

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

• MCPB (Manifest-Spezifikation + CLI): https://github.com/anthropics/mcpb

• Produktive Implementierung: ../spx-learning-square/mcp/ (esbuild-1-Datei-Bundle, mit eingebrannten Umgebungs-Labels, Backend generiert .mcpb dynamisch)