bookd

Lector de lectura con IA acompañante, local-first: los humanos leen EPUB, MOBI, AZW3 y Markdown en el navegador; la IA obtiene con precisión el libro actual, el capítulo, el CFI, el texto visible y las selecciones a través de MCP, y también puede saltar y resaltar en la dirección inversa.

Límites principales

• El renderizado del texto y el procesamiento de formatos no invocan modelos; los tokens de IA se usan solo para la conversación.

• bookd es un servicio residente HTTP + WebSocket; MCP es un cliente ligero stdio sin estado. Cerrar Claude Code no cierra el lector.

• Los archivos se escriben por defecto solo en ~/Books/bookd; el puente de estado de lectura escribe en .reading/state.json del proyecto actual.

• No se maneja DRM. Para PDF solo se acepta un convertidor local explícito; actualmente no se suben archivos a la GUI de MinerU ni se reinstala MinerU.

Related MCP server: EPUB Reader MCP Server

Inicio de este repositorio

Requiere Node.js 20 o superior.

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

Abre http://127.0.0.1:4123. start inicia el servicio en segundo plano; si el servicio ya está en ejecución, se reutiliza directamente. Para depurar se puede usar npm run dev; para ejecutar la compilación de producción en primer plano, npm start.

Importa archivos o directorios Markdown:

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

Una vez publicado en npm, la forma de inicio en una sola línea es:

npx -y bookd start

Integración con Claude Code

El repositorio ya incluye:

• .mcp.json: registra el MCP stdio de bookd.

• .claude/skills/bookd/SKILL.md: skill para abrir libros, leer el contexto y realizar operaciones inversas.

• .claude/launch.json: configuración del servicio local para el panel del navegador de Claude Code.

Al usar por primera vez el .mcp.json a nivel de proyecto, Claude Code pedirá que confirmes la confianza. Tras compilar e iniciar bookd, puedes decir «Abrir [título del libro]» en Claude Code o invocar directamente /bookd.

Puedes comprobar la configuración con claude mcp list; la primera vez que veas Pending approval es el estado esperado y debes aprobarlo una vez en la sesión del proyecto de Claude Code.

Para reutilizarlo en otros proyectos: coloca integrations/claude-code/SKILL.md en .claude/skills/bookd/SKILL.md del proyecto de destino y usa integrations/claude-code/mcp.example.json como .mcp.json del proyecto de destino.

Herramientas MCP

La entrada MCP también se puede ejecutar de forma independiente:

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

Disposición de datos

~/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 usa campos estables del puente de archivos:

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

Configuración

Verificación

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

Las pruebas cubren la importación de EPUB/Markdown, la extracción de capítulos lógicos, la búsqueda de texto completo, la doble escritura de anotaciones, la escritura atómica del estado, HTTP, WebSocket, las 8 herramientas MCP y procesos secundarios stdio reales.

La regresión con Chromium real también cubre EPUB, MOBI6 y AZW3/KF8 del mismo libro en chino: el spine/section original se fusiona en capítulos lógicos según el TOC del libro y se conserva el CFI de inicio del capítulo. Las carpetas Markdown se importan como «un archivo, un capítulo lógico»; los encabezados de segundo nivel dentro de un archivo no fragmentan el índice.

El cuerpo del libro electrónico lo renderiza foliate-js en un iframe. bookd elimina los scripts en línea y los manejadores de eventos e inyecta una CSP estricta; Chromium seguirá mostrando una advertencia de sandbox por el allow-scripts + allow-same-origin que foliate-js establece para la compatibilidad de eventos de WebKit. Es un aviso conocido de la implementación upstream y no significa que los scripts del libro tengan permiso para ejecutarse.

Estado de PDF / MinerU

El /Applications/MinerU.app actual de esta máquina es una GUI Electron conectada a la red y no proporciona el CLI mineru, por lo que la compilación actual informa explícitamente en /api/health que el PDF no está habilitado. La adaptación de PDF se mantiene fuera de las dependencias principales; solo debe habilitarse cuando se detecte un CLI local configurado explícitamente por el usuario, para evitar reinstalar Python/MinerU o subir documentos accidentalmente.

El registro por fases y la validación técnica están en PROGRESS.md.