{% extends "base.html" %} {% block title %}Dokumentation{% endblock %} {% block content %}

📚 Dokumentation – LLMWikiNG

Version {{ app_version }} · Vollständiges Handbuch für Einrichtung, Multi-Wiki, Authentifizierung und API.

🚀 Erste Schritte

  1. Abhängigkeiten installieren: pip install -r requirements.txt
  2. Server starten: ./start.sh (oder python3 run.py --port 8080)
  3. Beim ersten Start (Setup) wirst du automatisch auf /register umgeleitet, um den ersten Benutzer (Administrator) anzulegen.
  4. Im Browser öffnen: http://localhost:8080/LLMWikiNG/

Das ursprüngliche wiki/ wird beim ersten Start automatisch nach wikis/main/ verschoben (Daten bleiben erhalten).

🗂️ Mehrere Wikis (Unter-Wikis)

Jedes Wiki liegt in wikis/<name>/ und hat einen eigenen Namen. Über die WebUI lässt sich ein neues Wiki anlegen:

Der Basis-Pfad ist über die Umgebungsvariable LLMWIKI_BASE_PATH konfigurierbar (Standard: /LLMWikiNG), z. B. für example.com/LLMWikiNG/wiki/<Name>/.

🔐 Authentifizierung & Benutzerverwaltung

⚙️ Einstellungen (Settings-Tabs)

Die zentrale Konfigurationsseite /LLMWikiNG/settings ist in Tabs unterteilt:

🦈 Tailscale & Funnel Integration (Remote-Zugriff für Agenten)

LLMWikiNG enthält eine integrierte Same-Container Tailscale Integration (unter Einstellungen ➜ Tailscale). Damit kannst du deine Instanz im privaten Tailnet-Netzwerk bereitstellen oder per Tailscale Funnel öffentlich im Internet für externe KI-Agenten (z. B. Claude, Grok, Cursor, AGY) erreichbar machen – ohne Port-Forwarding, NGINX oder CGNAT-Probleme.

💾 Server-Backups

LLMWikiNG bietet ein vollständiges Backup-Management unter Einstellungen ➜ Backups (nur Admin). Backups werden als komprimierte .tar.xz-Archive erstellt und im data/-Verzeichnis gespeichert.

Backups können auch programmatisch über die API verwaltet werden (siehe API-Abschnitt unten).

🌐 API (JSON, Key-geschützt)

Alle Funktionen sind unter /LLMWikiNG/api/v1 per X-API-Key-Header erreichbar. Das Browser-Frontend nutzt automatisch Session-Cookie-Auth als Fallback.

⚙️ Antigravity AI-Skill Fernbedienung

Nutze die offizielle Fernbedienung (SKILL.md) für deinen Antigravity-Agenten zur automatischen Steuerung des Wikis.

📥 Skill herunterladen
MethodePfadBeschreibung
GET/api/v1/wikisAlle Wikis
GET/api/v1/wikis/<wiki>/pagesSeiten eines Wikis
GET/api/v1/wikis/<wiki>/pages/<slug>Eine Seite
GET/api/v1/wikis/<wiki>/tagsTags mit Seitenanzahl (optionaler Filter via ?tag=)
POST/api/v1/wikis/<wiki>/pagesSeite anlegen (Scope write)
POST/api/v1/wikis/<wiki>/pages/<slug>/exportSeite exportieren
POST/api/v1/wikis/<wiki>/ingestDatei hochladen (raw/)
GET/api/v1/wikis/<wiki>/pendingAusstehende Ingests
POST/api/v1/wikis/<wiki>/ingest/processIngest verarbeiten
GET/api/v1/search?q=&wiki=Volltextsuche (Unterstützt wiki=all für Cross-Wiki-Suche)
GET/api/v1/graph?wiki=Graph-Daten
GET/api/v1/stats?wiki=Statistik
GET/api/v1/lint?wiki=Linter
GET/api/v1/statusServerstatus
GET/api/v1/system/healthVollständiger Bereitschaftscheck: Sync-Status, Quellen-Freshness, Qualitätsprobleme, Tools, Cache und aggregierte Nutzung
GET/api/v1/wikis/<wiki>/usageLokale aggregierte Seitenzugriffe ohne Protokollierung von Suchanfragen oder Inhalten
GET/api/v1/system/statusSystem & Traffic (Admin)
POST/api/v1/system/syncSync aller Wikis (Admin)
GET/api/v1/system/auditAudit-Logs abrufen – filterbar nach Aktion, Benutzer, Zeitraum (Admin)
GET/audit/export?fmt=json|csvAudit-Logs als JSON oder CSV exportieren (Admin)
GET/api/v1/system/backupsServerseitige Backups auflisten (Admin)
POST/api/v1/system/backupsServerseitiges Backup erstellen (Admin)
POST/api/v1/system/backups/<file>/restoreServerseitiges Backup wiederherstellen (Admin)
DELETE/api/v1/system/backups/<file>Serverseitiges Backup löschen (Admin)
GET/api/v1/system/update/checkUpdate-Verfügbarkeit prüfen (Admin)
POST/api/v1/system/update/runUpdate ausführen (Admin)
GET/api/v1/usersBenutzer (Admin)
POST/api/v1/usersBenutzer anlegen (Admin)
DELETE/api/v1/users/<id>Benutzer löschen (Admin)
GET/api/v1/api-keysAPI-Keys (Admin)
POST/api/v1/api-keysKey erzeugen (Admin)
DELETE/api/v1/api-keys/<id>Key widerrufen (Admin)
GET/api/v1/mcp-keysMCP-Keys auflisten (Admin)
POST/api/v1/mcp-keysMCP-Key mit Tool-Berechtigungen erzeugen (Admin)
PUT/api/v1/mcp-keys/<id>MCP-Key bearbeiten – Name, User, Tools, Status (Admin)
DELETE/api/v1/mcp-keys/<id>MCP-Key widerrufen (Admin)
POST/wiki/<wiki>/api/ingestDirekter Ingest für spezifisches Wiki (API-Key)
POST/wiki/<wiki>/api/syncDirektes Syncen für spezifisches Wiki (API-Key)
GET/mcp/sseMCP SSE-Kanal für KI-Agenten (MCP API-Key)
POST/mcp/messagesMCP JSON-RPC Nachrichtenkanal (MCP API-Key)

📋 cURL-Befehlsbeispiele (Fernbedienung)

Exportiere deine Variablen, um die Befehle direkt zu kopieren:

export API_KEY="llmw_dein_key"
export SERVER_URL="http://localhost:8082/LLMWikiNG"
export WIKI="main"
1. Wikis auflisten:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis"
2. Wiki-Seiten auslesen:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis/$WIKI/pages"
3. Spezifische Seite abrufen:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis/$WIKI/pages/llm-wiki"
4. Neue Seite erstellen (YAML-Frontmatter-Pflicht):
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"slug":"api-test","content":"---\ntype: Concept\ntitle: API Test\ntimestamp: 2026-07-14T22:00:00Z\n---\n# API Test\nErfolgreich erstellt!"}' \
  "$SERVER_URL/api/v1/wikis/$WIKI/pages"
5. Direkter Multi-Wiki-Ingest (Datei, URL oder Text):
# URL-Ingest
curl -X POST -H "X-API-Key: $API_KEY" -d "url=https://de.wikipedia.org/wiki/Google" -d "title=Google" "$SERVER_URL/wiki/$WIKI/api/ingest"

# Datei-Upload
curl -X POST -H "X-API-Key: $API_KEY" -F "file=@/pfad/zur/datei.txt" "$SERVER_URL/wiki/$WIKI/api/ingest"

# Text-Paste
curl -X POST -H "X-API-Key: $API_KEY" -d "text=# Mein Text\nInhalt..." -d "title=Text-Paste" "$SERVER_URL/wiki/$WIKI/api/ingest"
6. Volltextsuche:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/search?q=Suchbegriff&wiki=$WIKI"
7. Wissensgraph-Netzwerk abrufen:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis/$WIKI/graph"
8. Benutzer anlegen (nur Admin):
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"username":"neuer_user","password":"sicheres_passwort","role":"editor"}' \
  "$SERVER_URL/api/v1/users"
9. API-Keys auflisten & generieren (nur Admin):
# Listen
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/api-keys"

# Erzeugen (optional mit require_password: true)
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Neuer Key","require_password":false,"scopes":["read","write"]}' \
  "$SERVER_URL/api/v1/api-keys"
10. MCP-Keys verwalten (nur Admin):
# MCP-Keys auflisten
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/mcp-keys"

# Neuen MCP-Key mit Tool-Berechtigungen erzeugen
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Cursor Agent","user_id":1,"allowed_tools":["okf_list_wikis","okf_read_concept","okf_search"]}' \
  "$SERVER_URL/api/v1/mcp-keys"
11. Update prüfen & ausführen (nur Admin):
# Update-Verfügbarkeit prüfen:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/system/update/check"

# Update ausführen:
curl -X POST -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/system/update/run"

🤖 Model Context Protocol (MCP)

LLMWikiNG stellt einen nativen Model Context Protocol (MCP) Server über HTTP-SSE bereit. Dies ermöglicht es KI-Assistenten (wie Cursor, OpenCode und dem Antigravity agy CLI), das Wiki im Open Knowledge Format (OKF v0.2) zu durchsuchen, zu lesen und zu beschreiben.

🔌 Endpunkt-Konfiguration

Konfiguriere den MCP-Server vor dem Start über Umgebungsvariablen:

# MCP aktivieren (Standard: true)
ENABLE_MCP_SERVER=true

# Endpunkte absichern (X-API-Key erforderlich)
LLMWIKING_MCP_KEY="dein_sicherer_mcp_key_2026"

Dies schaltet die MCP-Endpunkte unter folgenden URLs frei:

  • Streamable HTTP Endpunkt: http://localhost:8080/LLMWikiNG/mcp
  • SSE-Kanal: http://localhost:8080/LLMWikiNG/mcp/sse
  • Nachrichten-Kanal: http://localhost:8080/LLMWikiNG/mcp/messages

💻 Client-Konfigurationsbeispiele

1. Cursor IDE

Gehe in Cursor zu Settings ➜ Features ➜ MCP und klicke auf "+ Add New MCP Server":

  • Name: LLMWikiNG-OKF
  • Type: SSE
  • URL: http://localhost:8080/LLMWikiNG/mcp/sse
  • Headers: {"X-MCP-Key": "dein_sicherer_mcp_key_2026", "X-API-Key": "dein_datenbank_api_schluessel"}
2. OpenCode

Füge den Serverblock in deiner globalen (~/.config/opencode/opencode.json) oder projektspezifischen (opencode.json) Konfiguration hinzu:

{
  "mcp": {
    "llmwiking-okf": {
      "type": "remote",
      "url": "http://localhost:8080/LLMWikiNG/mcp/sse",
      "enabled": true,
      "headers": {
        "X-MCP-Key": "dein_sicherer_mcp_key_2026",
        "X-API-Key": "dein_datenbank_api_schluessel"
      }
    }
  }
}
3. Antigravity CLI (agy) & Antigravity IDE

Registriere den SSE-Server in deiner globalen MCP-Konfigurationsdatei unter ~/.gemini/config/mcp_config.json (oder projektbezogen unter .agents/mcp_config.json):

{
  "mcpServers": {
    "llmwiking-okf": {
      "type": "http",
      "url": "http://localhost:8080/LLMWikiNG/mcp",
      "headers": {
        "X-MCP-Key": "dein_sicherer_mcp_key_2026",
        "X-API-Key": "dein_datenbank_api_schluessel"
      }
    }
  }
}

⚡ MCP Prompts & Remote Slash Commands (38 Befehle)

Nach der Verbindung mit LLMWikiNG via MCP öffnet die Eingabe von / in unterstützten Clients (AGY, OpenCode, Cursor, Claude Code) das Slash-Command-Menü:

/update System-Update prüfen und ausführen
/ingest [wiki] Ausstehende Rohquellen verarbeiten
/backup Vollständiges Server-Backup erstellen
/search <query> [wiki] Wiki-Seiten durchsuchen
/status Systemstatus anzeigen
/lint [wiki] Wiki-Gesundheitsprüfung ausführen
/read <slug> [wiki] Wiki-Seite vollständig lesen
/sync [wiki] Matrix-Index synchronisieren

Der MCP Tool Explorer unter Einstellungen ➜ MCP in der WebUI bietet eine kategorisierte Akkordeon-Ansicht aller 47 Tools mit Beschreibungen, Parametern und fertigen Prompts. Der Interaktive Client-Konfigurator im selben Panel erlaubt es, einen Benutzer und dessen Schlüssel auszuwählen, um mit einem Klick ein fertiges Konfigurations-Snippet für AGY, OpenCode oder Hermes zu generieren.

⚠️ Fehlerbehebung: „Entschlüsselung fehlgeschlagen" bei API- & MCP-Keys:

Wenn beim Anzeigen/Entschlüsseln eines Schlüssels die Meldung "Entschlüsselung fehlgeschlagen. Das kryptografische System-Geheimnis unterscheidet sich..." erscheint, wurde dieser Schlüssel vor einer Änderung des System-Geheimnisses (secret_key in config.json) erstellt.

Lösung:
  1. Gehe zu Einstellungen ➜ API-Keys & MCP-Keys.
  2. Klicke auf den roten Button "🗑️ Alle API-Keys löschen" oder "🗑️ Alle MCP-Schlüssel löschen" im entsprechenden Bereich und bestätige mit deinem Admin-Passwort.
  3. Erstelle neue Schlüssel. Diese werden mit dem aktuellen System-Geheimnis in config.json verschlüsselt und bleiben dauerhaft entschlüsselbar.
🛡️ Sicherheits-Empfehlung:
Es wird dringend empfohlen, für jeden KI-Agenten / Client ein eigenes, eingeschränktes Benutzerkonto und einen spezifischen API-Schlüssel anzulegen (in der Web-Oberfläche unter Einstellungen ➜ Benutzer / Keys), anstatt dein Haupt-Administrator-Konto oder einen globalen Schlüssel zu teilen. Zusätzlich können Sie unter Einstellungen ➜ Keys ➜ MCP Keys benutzergebundene MCP-Schlüssel mit feingranularen Tool-Berechtigungen erstellen. Jeder MCP-Key ist einem bestimmten Benutzer zugeordnet und kann auf eine Teilmenge von Tools beschränkt werden (z. B. nur Lesezugriff). Dies sorgt für saubere, isolierte Audit-Logs und schränkt die Rechte des Agenten sinnvoll ein.
💬 Kopierbarer Prompt für KI-Assistenten (zur MCP-Einbindung):

Kopiere diesen Prompt und füge ihn in deinen KI-Assistenten (z. B. Cursor Chat, Claude Code, OpenCode oder agy) ein, damit dieser sich selbst mit dem MCP-Server verbindet:

Konfiguriere dich so, dass du dich mit dem LLMWikiNG-MCP-Server verbindest. Der Server nutzt SSE (Server-Sent Events) unter der URL: http://localhost:8080/LLMWikiNG/mcp/sse. Du musst die Header 'X-MCP-Key' mit dem Wert '<DEIN_MCP_SERVER_KEY>' und 'X-API-Key' mit dem Wert '<DEIN_AGENT_API_KEY>' mitsenden. In OpenCode füge dies unter 'mcp' in deiner Konfigurationsdatei hinzu. In Antigravity (agy) füge es unter 'mcpServers' in der Datei ~/.gemini/config/mcp_config.json hinzu.

🔑 Kryptografisches Geheimnis (LLMWIKI_SECRET)

Das System verwendet ein zentrales Geheimnis, um Browser-Sitzungscookies zu signieren und API-Schlüssel zu verschlüsseln. Es wird aus der Umgebungsvariablen LLMWIKI_SECRET ausgelesen oder beim ersten Start automatisch generiert und dauerhaft in der Datei config.json (unter dem Schlüssel "secret_key") gespeichert.

⚠️ Warnung zur Rotation des Geheimnisses:
Das Ändern des System-Geheimnisses führt zum sofortigen Ablauf aller aktiven Web-Sitzungen (erfordert eine erneute Anmeldung) und macht zuvor verschlüsselte API-Schlüssel unlesbar. Nach dem Ändern des Secrets müssen alte API-Keys gelöscht und in der Administration neu erstellt werden.

🌗 Erscheinungsbild (Theme)

Das Aussehen (Dark/Light) wird ausschließlich in den Einstellungen gesteuert und persistent in config.json gespeichert ("theme": "dark" bzw. "light"). Dark Mode ist Standard und wird server-seitig geladen – es gibt keine Umschalter-Buttons in der Sidebar.

🐋 Docker & UGreen NAS

Das Docker-Setup ist speziell für UGreen NAS-Systeme (UGOS) optimiert, um eine reibungslose Kompatibilität zu gewährleisten. Die Ordnerstruktur wird dabei automatisch unter volume1/docker/llmwiking/ abgelegt.

UGreen NAS (UGOS) Einrichtung:

Beim Importieren des Images in den UGreen Container Manager werden folgende Volumes vordefiniert:

Lokale Ausführung & Entwicklung:

Um das Setup auf einem anderen Host (z. B. lokal) auszuführen, ohne dass Mount-Fehler (z. B. durch config.json) auftreten, kann die Umgebungsvariable DOCKER_VOLUME_BASE genutzt werden:

  1. Erstelle eine lokale .env-Datei im Projektverzeichnis:
    DOCKER_VOLUME_BASE=.
  2. Starte den Container:
    docker compose up --build

🎨 Frontend (Tailwind CSS v4)

Das CSS wird über eine CSS-First-Pipeline gebaut (@theme mit oklch-Design-Tokens, Dark Mode, responsiv):

cd frontend && npm install && npm run build

base.html bindet static/css/tailwind-build.css ein; das gesamte JavaScript liegt als ES-Module unter static/js/.

⌨️ Wichtige Web-Routen

{% endblock %}