bookd

A local-first AI companion reader: humans read EPUB, MOBI, AZW3, and Markdown in the browser, while AI precisely retrieves the current book, chapter, CFI, visible text, and selection via MCP, and can also jump back and highlight.

Core boundaries

• Content rendering and format processing never call the model; AI tokens are used only for discussion.

• bookd is a resident HTTP + WebSocket service; MCP is a stateless stdio thin client. Closing Claude Code does not close the reader.

• Files are written only to ~/Books/bookd by default; the reading-state bridge writes to the current project's .reading/state.json.

• No DRM handling. PDF only accepts an explicitly configured local converter; the current build will not upload files to the MinerU GUI or reinstall MinerU.

Related MCP server: EPUB Reader MCP Server

Starting from this repository

Requires Node.js 20 or higher.

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

Open http://127.0.0.1:4123. start launches the service in the background; if the service is already running it is reused directly. For debugging use npm run dev; to run the production build in the foreground use npm start.

Import a file or a Markdown directory:

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

The one-line startup form after publishing to npm is:

npx -y bookd start

Claude Code integration

The repository already provides:

• .mcp.json: registers the bookd stdio MCP.

• .claude/skills/bookd/SKILL.md: a skill for opening books, reading context, and reverse operations.

• .claude/launch.json: local service configuration for the Claude Code Browser panel.

When using a project-level .mcp.json for the first time, Claude Code will ask you to confirm trust. After building and starting bookd, you can say "open 《book title》" in Claude Code or call /bookd directly.

You can first check the configuration with claude mcp list; seeing Pending approval the first time is expected, and you need to approve it once in the Claude Code project session.

To reuse in another project: put integrations/claude-code/SKILL.md into the target project's .claude/skills/bookd/SKILL.md, and use integrations/claude-code/mcp.example.json as the target project's .mcp.json.

MCP tools

The MCP entry point can also be run standalone:

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

Data layout

~/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 uses stable file-bridge fields:

{
  "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"
}

Configuration

Verification

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

Tests cover EPUB/Markdown import, logical chapter extraction, full-text search, annotation dual-write, atomic state writes, HTTP, WebSocket, the 8 MCP tools, and real stdio child processes.

Real Chromium regression also covers the same Chinese book in EPUB, MOBI6, and AZW3/KF8: the raw spine/sections are merged into logical chapters according to the in-book TOC, preserving the chapter-start CFI. Markdown folders are imported as "one file, one logical chapter"; second-level headings inside a file do not fragment the TOC.

Ebook content is rendered by foliate-js in an iframe. bookd removes inline scripts and event handlers and injects a strict CSP; Chromium will still emit a sandbox warning for the allow-scripts + allow-same-origin that foliate-js requires for WebKit event compatibility. This is a known upstream implementation notice and does not mean in-book scripts are allowed to execute.

PDF / MinerU status

The local /Applications/MinerU.app is a networked Electron GUI and does not provide a mineru CLI, so the current build explicitly reports PDF as disabled in /api/health. PDF adaptation stays outside the core dependencies; it should only be enabled after detecting a user-configured local CLI, to avoid reinstalling Python/MinerU or accidentally uploading documents.

Phase records and technical validation are in PROGRESS.md.