Foliant für D&D

Self-hosted MCP-Server als Regel-Nachschlagewerk für D&D 5e (Fassung 2024), Deutsch-first — kurz: Foliant. Beantwortet Regelfragen (Kampf + außerhalb), liefert Steckbriefe und unterstützt die Charaktererstellung — geerdet auf importierte Quellen, mit Quelle, Seite und Regelversion, in korrektem Spieldeutsch (englischer Begriff in Klammern, * wenn keine offizielle Übersetzung existiert).

Daneben läuft der Charakterbogen-Übersetzer: ein englischer D&D-Beyond-PDF-Export wird zum ausgefüllten offiziellen deutschen WotC-Bogen 2024, druckbar.

Der Kern in drei Sätzen

1. Geerdet: Foliant antwortet nur aus dem importierten Bestand; findet es nichts, sagt es das — statt zu erfinden. Websuche nur als klar gekennzeichneter Fallback, niemals Spoiler.
2. Deutsch-first: offizielle deutsche Begriffe, englisches Original in Klammern, * wenn keine offizielle Übersetzung existiert.
3. Version immer: aktuelle Regeln (2024) als Standard; ältere Stände klar gekennzeichnet.

Stand (03.08.2026)

MVP komplett und live auf einem Raspberry Pi 4: ~12 500 Einträge aus 18 Quellen (dt. SRD 5.2.1, drei deutsche 2014-Bücher, Open5e, D&D-Beyond-Bücher, drei Errata-Bände), 6 Tools, Zugang über geheimen Pfad + IP-Allowlist, Datenbank-QS abgeschlossen. Der Charakterbogen-Übersetzer läuft als eigener Container daneben, der Discord-Bot ebenso. Maßgeblich ist immer admin status. Was noch offen ist: BACKLOG.md.

Dokumentation — vier Dateien, mehr nicht

Datei	Enthält
SPEC.md	Das verbindliche „Was": Anforderungen, Sprach- und Versionsregeln, Verhalten, Abnahmekriterien (die Projektanweisung selbst steht in config/projektanweisung.md)
CONCEPT.md	Das „Wie": Architektur, Datenmodell, Import-Pipelines, Betrieb und Deployment, Entscheidungen, Fallen, Sicherheitsmodell
BACKLOG.md	Was offen ist: Phasen mit Gates, Abnahme-Checkliste, Rest-Posten, Ausbaustufen
README.md	Diese Datei: Einstieg, Schnellstart, Nutzung, Recht

CLAUDE.md ist kein fünftes Dokument, sondern der Einstiegspunkt für Claude Code — er verweist nur auf die vier oben.

Die Zuordnung ist getestet, nicht nur vereinbart: tests/test_doku_pflege.py (Teil von make test) prüft, dass §-Verweise ein Kapitel treffen, die Stand-Angaben zum Inhalt passen, jede Anforderung aus SPEC.md einen Status in BACKLOG.md hat, genannte Dateien existieren und keine Aussage wortgleich in zwei Dateien gepflegt wird.

Aufbau des Repositorys

app/         FastMCP-Server, Tools, Zugriffsschutz, Admin-CLI, Charakterbogen-Übersetzer
importer/    PDF · OCR · Markdown · Glossar · Open5e · DDB
db/          Schema + Init          config/   Verhaltensregeln + Config-Vorlage
tests/       Abnahme (T1–T12), Smoke, Golden-Suite am echten Bestand
deploy/      Caddyfile              .github/  CI

Schnellstart (Entwicklung am Mac)

python -m venv .venv && .venv/bin/pip install -r requirements.txt
python db/init_db.py data/foliant.sqlite
cp config/foliant.example.toml config/foliant.toml    # Quellen/Pfade eintragen
python -m app.admin import --quelle srd-de            # bzw. open5e-srd-2024, glossar
make test                                             # das EINE Gate
.venv/bin/uvicorn app.server:app --port 8000          # GET /ready == 200

Der MCP-Endpoint liegt lokal unter http://localhost:8000/mcp (Dev ohne Geheimpfad).

Foliant in Discord