bookd

Lokaler KI-Begleitleser: Menschen lesen EPUB, MOBI, AZW3 und Markdown im Browser, die KI erhält über MCP präzise das aktuelle Buch, Kapitel, CFI, sichtbaren Text und Auswahlen und kann auch zurückspringen und hervorheben.

Kernabgrenzungen

• Die Darstellung des Textinhalts und die Formatverarbeitung rufen keine Modelle auf; KI-Token werden nur für Diskussionen verwendet.

• bookd ist ein dauerhaft laufender HTTP- + WebSocket-Dienst; MCP ist ein zustandsloser dünner stdio-Client. Das Schließen von Claude Code schließt den Reader nicht.

• Dateien werden standardmäßig nur nach ~/Books/bookd geschrieben; die Lesezustands-Brücke schreibt in .reading/state.json des aktuellen Projekts.

• DRM wird nicht behandelt. Für PDF werden nur ausdrücklich konfigurierte lokale Konverter akzeptiert; Dateien werden derzeit nicht in die MinerU-GUI hochgeladen und MinerU wird nicht erneut installiert.

Related MCP server: EPUB Reader MCP Server

Start aus diesem Repository

Erfordert Node.js 20 oder höher.

npm install
npm run build
node dist/cli.js start

Öffne http://127.0.0.1:4123. start startet den Dienst im Hintergrund; wenn der Dienst bereits läuft, wird er direkt wiederverwendet. Zum Debuggen kann npm run dev verwendet werden, für den Produktions-Build im Vordergrund npm start.

Dateien oder Markdown-Verzeichnisse importieren:

node dist/cli.js import /path/to/book.epub
node dist/cli.js import /path/to/markdown-directory

Nach der Veröffentlichung auf npm lautet die Ein-Zeilen-Startform:

npx -y bookd start

Integration mit Claude Code

Im Repository sind bereits enthalten:

• .mcp.json: registriert bookd als stdio-MCP.

• .claude/skills/bookd/SKILL.md: Skill zum Öffnen von Büchern, Lesen des Kontexts und für Rückwärtsaktionen.

• .claude/launch.json: lokale Dienstkonfiguration für das Browser-Panel von Claude Code.

Bei der ersten Verwendung der projektweiten .mcp.json fordert Claude Code eine Vertrauensbestätigung an. Nachdem bookd gebaut und gestartet wurde, kannst du in Claude Code „Öffne ‚Buchtitel‘“ sagen oder direkt /bookd aufrufen.

Du kannst die Konfiguration zuerst mit claude mcp list prüfen; Pending approval beim ersten Mal ist ein erwarteter Zustand und muss einmal in der Projektsitzung von Claude Code genehmigt werden.

Zur Wiederverwendung in anderen Projekten: Lege integrations/claude-code/SKILL.md in .claude/skills/bookd/SKILL.md des Zielprojekts und verwende integrations/claude-code/mcp.example.json als .mcp.json des Zielprojekts.

MCP-Tools

Der MCP-Einstiegspunkt kann auch separat ausgeführt werden:

BOOKD_URL=http://127.0.0.1:4123 node dist/mcp.js

Datenlayout

~/Books/bookd/<书名>/
├── source.epub              # 或 source.mobi / source.azw3 / source.md
├── extracted/               # 按逻辑章节缓存的 Markdown
├── chapters.json            # 搜索与 MCP 的结构化章节缓存
├── annotations.json         # 结构化批注
├── notes.md                 # 人可读、Git 友好的批注
└── meta.json

<当前项目>/.reading/state.json

state.json verwendet stabile Dateibrücken-Felder:

{
  "book": "随椋鸟飞行",
  "chapter": "与椋鸟齐飞",
  "chapter_index": 1,
  "cfi": "epubcfi(/6/12!/4/2)",
  "progress": 0.09,
  "visible_text_head": "当前屏幕内的文字…",
  "selection": null,
  "updated_at": "2026-08-06T00:00:00.000Z"
}

Konfiguration

Verifizierung

npm run check
npm audit --omit=dev
npm pack --dry-run

Die Tests decken EPUB-/Markdown-Import, logische Kapitelgewinnung, Volltextsuche, Doppelausgabe von Anmerkungen, atomares Schreiben des Zustands, HTTP, WebSocket, die 8 MCP-Tools und echte stdio-Subprozesse ab.

Echte Chromium-Regressionstests decken außerdem EPUB, MOBI6 und AZW3/KF8 desselben chinesischen Buchs ab: Die ursprünglichen spine/section-Einträge werden anhand des buchinternen TOC zu logischen Kapiteln zusammengeführt, wobei die CFI der Kapitelanfänge erhalten bleibt. Markdown-Ordner werden nach dem Prinzip „eine Datei = ein logisches Kapitel“ importiert; Überschriften der zweiten Ebene innerhalb einer Datei zerstückeln das Inhaltsverzeichnis nicht.

Der E-Book-Text wird von foliate-js in einem iframe gerendert. bookd entfernt Inline-Skripte und Ereignisbehandler und injiziert eine strenge CSP; Chromium gibt dennoch eine Sandbox-Warnung für allow-scripts + allow-same-origin aus, das foliate-js für die WebKit-Ereigniskompatibilität gesetzt hat. Dies ist ein bekannter Hinweis auf die Upstream-Implementierung und bedeutet nicht, dass Skripte im Buch ausgeführt werden dürfen.

PDF-/MinerU-Status

Das lokal vorhandene /Applications/MinerU.app ist eine netzwerkfähige Electron-GUI und stellt keine mineru-CLI bereit. Daher meldet der aktuelle Build unter /api/health ausdrücklich, dass PDF nicht aktiviert ist. Die PDF-Anbindung bleibt außerhalb der Kernabhängigkeiten; sie soll nur aktiviert werden, wenn eine vom Benutzer ausdrücklich konfigurierte lokale CLI erkannt wird, um eine erneute Installation von Python/MinerU oder versehentliches Hochladen von Dokumenten zu vermeiden.

Phasenprotokoll und technische Verifizierung siehe PROGRESS.md.