bookd

Локально-ориентированная читалка с ИИ-компаньоном: человек читает EPUB, MOBI, AZW3 и Markdown в браузере, а ИИ через MCP точно получает текущую книгу, главу, CFI, видимый текст и выделения, а также может переходить и подсвечивать в обратную сторону.

Ключевые границы

• Рендеринг текста и обработка форматов не вызывают модель; токены ИИ используются только для обсуждения.

• bookd — это постоянный HTTP + WebSocket сервис; MCP — тонкий клиент без состояния на stdio. Закрытие Claude Code не закрывает читалку.

• Файлы по умолчанию записываются только в ~/Books/bookd, мост состояния чтения записывается в .reading/state.json текущего проекта.

• DRM не обрабатывается. PDF принимается только через явно настроенный локальный конвертер; файлы не загружаются в GUI MinerU и MinerU не устанавливается повторно.

Related MCP server: mcp-ebook-server

Запуск из этого репозитория

Требуется Node.js 20 или новее.

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

Откройте http://127.0.0.1:4123. start запускает сервис в фоне; если сервис уже запущен, он переиспользуется. Для отладки можно использовать npm run dev, для запуска продакшен-сборки на переднем плане — npm start.

Импорт файлов или каталога Markdown:

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

После публикации в npm однострочный запуск выглядит так:

npx -y bookd start

Интеграция с Claude Code

В репозитории уже предоставлено:

• .mcp.json: регистрирует stdio MCP bookd.

• .claude/skills/bookd/SKILL.md: навык открытия книг, чтения контекста и обратных операций.

• .claude/launch.json: конфигурация локального сервиса для панели Browser в Claude Code.

При первом использовании проектного .mcp.json Claude Code запросит подтверждение доверия. После сборки и запуска bookd можно сказать в Claude Code «Открой „Название книги“» или напрямую вызвать /bookd.

Можно сначала проверить конфигурацию с помощью claude mcp list; при первом запуске статус Pending approval — это ожидаемое состояние, его нужно одобрить один раз в сессии проекта Claude Code.

Для переиспользования в другом проекте: поместите integrations/claude-code/SKILL.md в .claude/skills/bookd/SKILL.md целевого проекта, а integrations/claude-code/mcp.example.json используйте как .mcp.json целевого проекта.

Инструменты MCP

Вход MCP также можно запускать отдельно:

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

Расположение данных

~/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 использует стабильные поля файлового моста:

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

Конфигурация

Проверка

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

Тесты покрывают импорт EPUB/Markdown, извлечение логических глав, полнотекстовый поиск, двойную запись аннотаций, атомарную запись состояния, HTTP, WebSocket, 8 инструментов MCP и реальный дочерний процесс stdio.

Регрессия на реальном Chromium также покрывает EPUB, MOBI6, AZW3/KF8 одной и той же китайской книги: исходные spine/section объединяются в логические главы по TOC внутри книги, сохраняя CFI начала глав. Папка Markdown импортируется по принципу «один файл — одна логическая глава», подзаголовки второго уровня внутри файла не разбивают оглавление.

Текст электронной книги рендерится foliate-js в iframe. bookd удаляет встроенные скрипты и обработчики событий и внедряет строгий CSP; Chromium всё равно выдаёт предупреждение песочницы для allow-scripts + allow-same-origin, которые foliate-js устанавливает для совместимости с событиями WebKit — это известное замечание реализации вышестоящего проекта, а не разрешение на выполнение скриптов книги.

Статус PDF / MinerU

Установленный локально /Applications/MinerU.app — это сетевой Electron GUI без CLI mineru, поэтому текущая сборка явно сообщает в /api/health, что PDF не включён. Адаптер PDF остаётся вне основных зависимостей; он должен включаться только при обнаружении явно настроенного пользователем локального CLI, чтобы избежать повторной установки Python/MinerU или случайной загрузки документов.

Этапные записи и технические проверки см. в PROGRESS.md.