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.

Related MCP server: dnd-oracle

Stand (26.08.2026)

Läuft, wird benutzt — der Tisch-Test steht noch aus. Der Server läuft auf einem Raspberry Pi 4: 12 545 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. Seit dem 26.08.2026 hängt der MCP am geteilten Router des Geräts (mcp.magnetron.me), dnd.magnetron.me trägt nur noch die Website. Charakterbogen-Übersetzer und Discord-Bot laufen als eigene Container daneben; der Bot beantwortet seit Ende Juli Fragen der Runde und hat zwei Rückmeldungsdurchgänge geliefert. Maßgeblich für den Bestand ist immer admin status.

Was das nicht heißt: Eine Spielrunde hat damit noch nicht gearbeitet, und bis ein Off-Site-Ziel steht, liegen Bestand und Backup auf derselben SD-Karte. Details und der Rest der offenen Posten: BACKLOG.md.

Dokumentation — vier Dateien, mehr nicht

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 und untereinander nicht auseinanderlaufen, 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). Im Container-Betrieb gibt es keinen Host-Port: dort führt der Weg über den vorgelagerten MCP-Router (CONCEPT.md §9).

Foliant in Discord

Auf dem Server der Runde: /regel <frage> eingeben oder @Foliant erwähnen — die Antwort öffnet einen Thread, in dem Nachfragen mit Gesprächskontext möglich sind — auch nach einem Server-Neustart, denn der Bot liest den Thread dann aus der Discord-Historie zurück. Wer nur für sich nachschlagen möchte, nimmt /regel-privat <frage>: die Antwort sieht dann niemand sonst, dafür gibt es keinen Thread für Nachfragen. Es gilt ein gemeinsames Tageslimit als Kostendeckel.

/bestand zeigt, welche Bücher im Bestand stehen — mit Sprache, Regelstand und Umfang, gruppiert wie auf der Website. Ephemer und ohne API-Kosten, weil die Liste direkt aus der Datenbank kommt.

War eine Antwort falsch? Mit 👎 darauf reagieren — Foliant merkt sich die Frage als Korrektur-Kandidaten (📝 heißt: notiert) und wird genau dort besser, wo er heute daneben liegt. Reaktion wegnehmen löscht den Eintrag. Einrichtung (einmalig, Betreiber): CONCEPT.md §9 „Discord-Bot einrichten".

Betrieb, Deployment und die Import-Wege im Detail: CONCEPT.md §8–9.

Nutzung

Foliant im Claude-Chat

Custom Connector mit der vollen URL inkl. Geheimpfad hinzufügen — https://<host>/<token>/foliant, kein OAuth. Einrichten am Desktop; benutzen geht danach auch aus der Mobile-App. Für konsistentes Verhalten die Projektanweisung in ein Claude-Projekt einfügen — sie steht kopierbereit auf der Charakterbogen-Website im Abschnitt „Foliant im Claude-Chat“ (der gemeinsame Ort für alle Mitspieler; Quelle ist config/projektanweisung.md).

Charakterbogen-Übersetzer — Kurzanleitung für die Runde

Ihr habt euren Charakter in D&D Beyond, aber der Bogen ist auf Englisch? Auf der Seite macht ihr daraus in etwa einer Minute einen deutschen Charakterbogen auf der offiziellen deutschen WotC-Vorlage (2024) — fertig zum Ausdrucken.

1. Anmelden. Es gibt nur ein Feld: das Kennwort. Kein Benutzername, keine Registrierung. Danach bleibt ihr 30 Tage angemeldet.

2. Bei D&D Beyond exportieren. Charakter öffnen → Character Sheet → Print/Export → als englisches PDF speichern.

3. PDF hochladen, etwa eine Minute warten, herunterladen. Das war's.

Häufige Fragen

• Was passiert mit meinen Daten? Nichts wird gespeichert. Das PDF wird nur im Arbeitsspeicher verarbeitet; nach dem Download ist alles weg.

• Funktioniert ein deutscher DDB-Export? Nein — nur englische Exporte.

• Warum hat mein Bogen plötzlich mehr Seiten? Passt der Inhalt nicht auf die zwei Seiten der Vorlage, kommt automatisch eine Anhang-Seite dazu. Es geht nichts verloren.

• Was bedeutet das Sternchen? Zum Beispiel „Angriffe abwehren* (Deflect Attacks)": Für diesen Begriff gibt es (noch) keine offizielle deutsche Fassung — das ist eine sinngemäße Übersetzung, das Original steht in Klammern. Begriffe ohne Sternchen sind die amtlichen Bezeichnungen.

• „Gerade belegt"? Es läuft immer nur eine Konvertierung gleichzeitig. Kurz warten.

Eine Bitte: Behaltet URL und Kennwort in der Runde — bitte nicht weitergeben. Danke! 🎲

Öffentlicher Code, private Inhalte

Dieses Repository enthält den Quellcode und die SRD-5.2.1-Import-Pipeline (CC-BY-4.0) als vollständiges Referenzbeispiel. Es enthält keine kommerziellen Regelinhalte. Die aus gekauften Druck-Büchern abgeleiteten Import-Reparaturen liegen bewusst in privaten, gitignorierten Modulen (importer/frhof_reparatur.py, importer/reparatur_ddb_privat.py, tests/test_ddb_druck_privat.py). Ohne sie bleibt der Server voll funktionsfähig — nur die kommerziellen Druck-Importe entfallen, die zugehörigen Tests überspringen sich selbst.

Mitwirken

Vor dem ersten Beitrag bitte die vier nicht verhandelbaren Kernregeln in SPEC.md §7 lesen — sie prägen fast jede Designentscheidung. Für Pull Requests gilt: make test muss grün sein, neue Funktionalität braucht Tests, Bugfixes brauchen einen Regressionstest, der ohne den Fix fehlschlägt. Der Code ist durchgehend deutschsprachig kommentiert; halte dich an den vorhandenen Stil. Details: CONCEPT.md §11.

Nicht ins Repository gehören: Geheimnisse (.env, Token, DDB-Cobalt), Datenbanken (data/), Quell-PDFs (quellen/) — alle bereits gitignored — und kommerzielle Regelinhalte. Bitte auch keine urheberrechtlich geschützten Regeltexte in Issues zitieren.

Nach dem Klonen einmalig die Hooks scharfschalten — ein pre-push-Wächter hält den privaten Archiv-Branch und die gitignorierten Reparaturmodule aus dem öffentlichen Repo, auch bei git push --all:

git config core.hooksPath .githooks

Sicherheitslücken bitte nicht über öffentliche Issues melden, sondern über die private „Report a vulnerability"-Funktion (GitHub → Security → Advisories). Das Sicherheitsmodell steht in CONCEPT.md §13.

Umgangston: freundlich, respektvoll, sachlich — im Zweifel gilt der Contributor Covenant.

Lizenz & Recht

• Code: MIT — siehe LICENSE.

• SRD 5.2.1: Dieses Projekt nutzt Material aus dem System Reference Document 5.2.1 („SRD 5.2.1") von Wizards of the Coast LLC, verfügbar unter https://www.dndbeyond.com/srd. Das SRD 5.2.1 steht unter der Creative Commons Attribution 4.0 International License (https://creativecommons.org/licenses/by/4.0/legalcode).

• Open5e (api.open5e.com): OGL 1.0a (srd-2014) bzw. CC-BY-4.0 (srd-2024); Attribution gemäß den jeweiligen Open5e-Dokumenten.

• Offizielle Errata (PHB/DMG/MM): von Wizards of the Coast frei zum Herunterladen angeboten, aber nicht frei lizenziert — „frei verteilt" ist keine offene Lizenz. Sie werden wie die Kaufbücher behandelt (nicht mitgeliefert, nur für den Eigenbedarf) und tragen deshalb lizenz = "WotC (frei verteilt, keine offene Lizenz)". Der Präfix CC-BY wird bewusst vermieden: er löst in der Ausgabe automatisch die SRD-Attribution aus, und die wäre hier eine falsche Rechtsaussage.

• Deutsche Begriffe u. a. über dnddeutsch.de (Ulisses-Terminologie).

• Offizieller deutscher Charakterbogen (2024): urheberrechtlich geschützte WotC-Vorlage. Sie ist nicht Teil des Repositorys (gitignored); der Charakterbogen-Übersetzer druckt die übersetzten Werte auf eine lokal vorgehaltene Kopie und gibt das Ergebnis an den Spieler zurück, dem die Daten ohnehin gehören. Weitergabe über die eigene Runde hinaus findet nicht statt.

• Kommerzielle D&D-Bücher (z. B. via D&D Beyond) sind urheberrechtlich geschützt, werden nicht mitgeliefert und nur privat, rechtmäßig erworben und zum Eigenbedarf verarbeitet (lizenz = "privat", herkunft = "ddb" an jedem Eintrag). Sie werden der eigenen Spielrunde über einen zugangsgeschützten Endpoint bereitgestellt — bewusste, protokollierte Eigentümer-Entscheidung (SPEC.md §12 Nr. 1). Eine Weitergabe über die Runde hinaus findet nicht statt.