Bidirektionale Anbindung beliebiger LLM-Chats und Agenten an das Liberino Lore- & Branch-System über das Model Context Protocol (MCP) und Command Line Interface (CLI).

MCP Server & Liberino CLI

Mit dem Liberino Model Context Protocol (MCP) Server und der Liberino CLI können beliebige LLM-Umgebungen (Claude Desktop, Cursor, Antigravity IDE, ChatGPT Desktop, Zed, Terminal-Agenten wie Aider oder Bash-Pipelines) nativ, universell und buchagnostisch mit dem Lore-System und der multidimensionalen Branch-State-Machine interagieren.

1. Architektur-Übersicht

flowchart TD
    subgraph Clients["LLM Clients & Agenten"]
        Claude["Claude Desktop"]
        Cursor["Cursor / Antigravity IDE"]
        TerminalAgent["Terminal / Bash / Aider"]
        WebAgent["Remote Agenten / Webhook"]
    end

    subgraph Interfaces["Schnittstellen"]
        MCP_STDIO["MCP Server (STDIO)<br/><code>npm run mcp:stdio</code>"]
        MCP_SSE["MCP Server (SSE / HTTP)<br/><code>GET /api/mcp/sse</code>"]
        CLI["Liberino CLI<br/><code>npm run cli -- ...</code>"]
    end

    subgraph CoreServices["Liberino Core Layer"]
        BranchResolver["BranchLoreResolverService<br/>(DAG Replay Machine)"]
        LoreFormatter["LoreProfileFormatterService<br/>(Markdown & Negative Rules)"]
        AgenticLore["AgenticLoreService<br/>(Search & Consistency Audit)"]
    end

    subgraph Persistence["Directus Headless CMS"]
        DirectusDB[("Directus API<br/>lore_entities, lore_states, scenes, books")]
    end

    Claude -->|STDIO JSON-RPC| MCP_STDIO
    Cursor -->|STDIO JSON-RPC| MCP_STDIO
    TerminalAgent -->|CLI Commands| CLI
    WebAgent -->|SSE / HTTP| MCP_SSE

    MCP_STDIO --> CoreServices
    MCP_SSE --> CoreServices
    CLI --> CoreServices

    CoreServices --> DirectusDB

2. MCP Server

Der Liberino MCP Server implementiert das standardisierte Model Context Protocol von Anthropic und registriert Tools, Resources und Prompt Templates.

Registrierte MCP Tools

Tool	Argumente	Beschreibung
`list_books`	keine	Listet alle Bücher mit ID, Titel, Serien-Referenz und Erstellungsdatum auf.
`search_lore`	`query`, `bookId?`, `type?`, `limit?`	Durchsucht Kanon-Entitäten (Charaktere, Orte, Objekte, Fraktionen, Regeln) per Volltext und Alias.
`get_entity_profile`	`entityIdOrName`, `bookId?`, `format?`	Liefert das vollständige kanonische Dossier (Aussehen, Farbpalette, Negativ-Regeln, Referenzbilder).
`resolve_branch_state`	`bookId`, `traversalPath`, `targetSceneId?`, `perspectiveEntityId?`, `entityIds?`	Multidimensionale State-Machine: Berechnet akkumulierte physische Zustände ($S_0 \oplus \sum \Delta$) wie Wunden, Kleidung, getragene Props und Gemütszustand an einem Handlungszweig.
`simulate_branch_path`	`bookId`, `traversalPath`, `entityIds?`	Simuliert die chronologische Entwicklung aller Figuren Szene für Szene entlang eines Pfades.
`record_state_delta`	`entityId`, `sourceSceneId?`, `chapterId?`, `statePatch`	Schreibt neue bitemporale Deltas (z. B. Verletzung am Flügel, erhaltene Gegenstände, Stimmungswechsel) in die Datenbank.
`create_lore_entity`	`bookId`, `type`, `name`, `staticTraits`	Registriert eine neue Kanon-Entität in der Lore-Bibel.
`audit_scene_consistency`	`bookId`, `sceneText`, `sceneTitle?`	Führt einen automatischen Konsistenz-Audit eines Szenentextes gegen Kanonregeln durch.
`list_scenes`	`bookId`, `chapterId?`	Listet alle Kapitel und Szenen eines Buches auf.
`create_scene`	`bookId`, `title`, `chapterId?`, `sceneNumber?`, `rawText?`	Erstellt eine neue Szene in der Directus-Datenbank.
`fork_branch`	`bookId`, `parentSceneId`, `branches`	Verzweigt eine Geschichte an einer Szene in mehrere Pfade samt automatischer Figuren-Zustands-Deltas.
`get_current_position`	keine	Git-Status-Äquivalent: Gibt Buch, Szene, aktiven Branch, Pfad und aktuelle Figuren-Zustände aus.
`checkout_branch`	`sceneId`, `bookId?`, `branchId?`, `traversalPath?`	Git-Checkout-Äquivalent: Setzt den aktiven Arbeitsfokus (HEAD) auf eine Szene/einen Zweig.
`get_cost_summary`	`hours?`	Gibt die kumulierten AI-Inferenzkosten (Euro & USD) der letzten 24h und aller Zeiten aus.
`visualize_entity_graph`	`entityIdOrName`, `bookId?`, `traversalPath?`	Visualisiert die Verzweigungshistorie einer Figur als Mermaid-Diagramm und Konsolenbaum.
`list_styles`	`search?`, `type?`	Listet alle 25+ Stile inklusive Prompt-Modifiern und Master-Sheet-Vorschaupfaden auf.
`get_style`	`styleIdOrSlug`	Ruft Details eines Stils ab und gibt alle 4 Master-Sheets als Chat-Bilder zurück.
`generate_reference_card`	`entityName`, `entityType?`, `styleIdOrSlug?`, `visualTraits?`, `negativeRules?`	Generiert einen isolierten 3-Ansichten-Modellbogen (nutzt automatisch den aktiven Branch-Zustand).
`approve_reference_card`	`entityIdOrName`, `imagePathOrFilename`, `visualTraitsSnippet?`	Fixiert die generierte Karte kanonisch in Directus `lore_entities.static_traits`.
`get_user_quota`	`apiKey?`	Liefert das aktuelle Token- & Budgetkontingent, Tarif (Free/Creator/Pro/Enterprise) und verbleibende Tokens aus dem Fast In-Memory Ledger.
`sync_user_tokens`	keine	Forciert die sofortige Write-Behind-Synchronisation aller geänderten Token-Zähler nach Directus und in den lokalen Backup-Ledger.

In-Memory Token Quota & Hard-Limit Guard

Der MCP Server schützt vor unkontrolliertem Budget- und Token-Verbrauch:

O(1) Memory Mapping: Jeder authentifizierte API-Key wird beim Serverstart in einer ultraschnellen In-Memory-Map (accountsByApiKey) gehalten. Keine Datenbank-Latenz bei Tool-Aufrufen!
Hard-Limit Guard: Überschreitet ein Nutzer sein Token-Kontingent oder das Euro-Budgetlimit (z. B. 5,00 € im Creator-Paket), blockieren generative Tools (create_lore_entity, record_state_delta, audit_scene_consistency, simulate_branch_path, generate_reference_card) sofort mit einem klaren Hinweis.
Write-Behind Persistence: Geänderte Token-Zähler werden alle 30 Sekunden sowie bei einem Server-Shutdown (SIGTERM, SIGINT) atomar nach Directus (members) und in data/user_quotas.json zurückgeschrieben.

MCP Resources

Clients können kanonische Lore-Ressourcen direkt per URI als Kontext einbinden:

lore://books/{bookId}/bible: Vollständiger, formatierter Markdown-Katalog aller Entitäten im Universum des Buches.
lore://books/{bookId}/entities/{entityId}: Detaillierte Karteikarte einer einzelnen Entität mit Negativ-Regeln und Historie.
lore://books/{bookId}/branches: Serialisierter DAG-Baum aller Kapitel und Szenen.

MCP Prompts

write-scene-with-branch-state: Führt ein LLM strukturiert durch das Schreiben einer Szene, indem automatisch alle aktiven Wunden, Props und Verhaltensregeln der anwesenden Figuren injiziert werden.

3. Client-Konfiguration

A. Claude Desktop

Füge in ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "liberino": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/harth/Documents/WORKSPACES/FLORIAN/liberino-ai/src/mcp/stdio.ts"
      ],
      "env": {
        "DIRECTUS_URL": "https://laefnabeiafnaleiafafe.2.28.78.110.sslip.io",
        "DIRECTUS_TOKEN": "..."
      }
    }
  }
}

B. Cursor / Antigravity IDE

In .cursor/mcp.json oder über die IDE-Einstellungen:

{
  "mcpServers": {
    "liberino": {
      "command": "npm",
      "args": ["--prefix", "/Users/harth/Documents/WORKSPACES/FLORIAN/liberino-ai", "run", "mcp:stdio"]
    }
  }
}

C. Remote / SSE Transport (Fastify)

Der Fastify-Server stellt SSE-Endpunkte bereit:

SSE Verbindungsaufbau: GET /api/mcp/sse
JSON-RPC Nachrichten: POST /api/mcp/messages?sessionId={id}
Status & Metriken: GET /api/mcp/status

4. Liberino CLI

Die CLI steht über npm run cli -- ... oder direkt als Binary liberino bereit:

Bücher inspizieren

# Alle Bücher auflisten
npm run cli -- books list

# Details zu einem Buch abrufen
npm run cli -- books get <book-id>

Lore durchsuchen & abrufen

# Kanonische Lore durchsuchen
npm run cli -- lore search "Drache" --book <book-id>

# Vollständiges Figuren-/Objekt-Dossier im Terminal anzeigen
npm run cli -- lore get <entity-id>

# Rohdaten als JSON ausgeben (z. B. für Skripte oder jq)
npm run cli -- lore get <entity-id> --format json

Branch-Status & Aktiver Arbeitskontext (HEAD)

# Wo befinde ich mich gerade im Story-Graph?
npm run cli -- branch status

# Zu einer anderen Szene / einem anderen Branch wechseln
npm run cli -- branch checkout <scene-id> --branch "branch-verletzung"

Multidimensionale Branch-State-Auflösung

# Wie ist der physische Zustand einer Figur an Szene B auf Zweig [A -> B]?
npm run cli -- branch resolve \
  -b <book-id> \
  -p "<scene_1_id>,<scene_2_id>" \
  -e <entity-id>

# Gesamte Pfad-Evolution simulieren
npm run cli -- branch simulate \
  -b <book-id> \
  -p "<scene_1_id>,<scene_2_id>,<scene_3_id>"

Zustands-Deltas & neue Figuren anlegen

# Neues State-Delta (Verletzung, Gegenstand, Gemütszustand) eintragen
npm run cli -- lore patch \
  -e <entity-id> \
  -s <scene-id> \
  --injury "Verstauchter Flügel nach Sturz in Höhle" \
  --body-part "Linker Flügel" \
  --mood "Erschöpft aber erleichtert"

# Neue Figur in der Lore-Bibel anlegen
npm run cli -- lore create \
  -b <book-id> \
  -n "Muriel die Muräne" \
  -t character \
  -d "Eine uralte, weise Muräne aus dem Nordmeer" \
  --tier supporting

Stile inspizieren & Referenzkarten erstellen

# Alle verfügbaren Bildstile auflisten
npm run cli -- styles list

# Details und Master-Sheet-Vorlagen eines Stils ansehen
npm run cli -- styles get whimsical-storybook

# 3-View Turnaround-Referenzkarte generieren
npm run cli -- card generate "Balthasar" \
  --type character \
  --style whimsical-storybook \
  --desc "Ein neugieriger kleiner Walddachs mit alter Brille" \
  --traits "Graues Fell, runde Nickelbrille, moosgrüne Weste" \
  --negative "keine Flügel" "keine Waffen"

# Referenzkarte genehmigen und als kanonisches Vorbild speichern
npm run cli -- card approve "Balthasar" "public/generated-references/ref_balthasar_123.png"

MCP Server & Liberino CLI

On this page