bookd

로컬 우선 AI 동반 독서 리더: 인간은 브라우저에서 EPUB, MOBI, AZW3 및 Markdown을 읽고, AI는 MCP를 통해 현재 책, 챕터, CFI, 보이는 텍스트와 선택 영역을 정확히 가져오며, 역방향 점프와 하이라이트도 가능합니다.

핵심 경계

• 본문 렌더링과 형식 처리는 모델을 호출하지 않습니다. AI 토큰은 토론에만 사용됩니다.

• bookd는 상주 HTTP + WebSocket 서비스입니다. MCP는 무상태 stdio 얇은 클라이언트입니다. Claude Code를 종료해도 리더는 종료되지 않습니다.

• 파일은 기본적으로 ~/Books/bookd에만 기록되며, 읽기 상태 브리지는 현재 프로젝트의 .reading/state.json에 기록됩니다.

• DRM은 처리하지 않습니다. PDF는 명시적인 로컬 변환기만 허용합니다. 현재 파일을 MinerU GUI에 업로드하거나 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: bookd stdio MCP 등록.

• .claude/skills/bookd/SKILL.md: 책 열기, 컨텍스트 읽기 및 역방향 작업을 위한 skill.

• .claude/launch.json: Claude Code Browser 패널의 로컬 서비스 구성.

프로젝트 수준 .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 폴더는 "파일 하나 = 논리 챕터 하나"로 가져오며, 파일 내 2단계 제목이 목차를 쪼개지 않습니다.

전자책 본문은 foliate-js가 iframe에서 렌더링합니다. bookd는 인라인 스크립트와 이벤트 핸들러를 제거하고 엄격한 CSP를 주입합니다. Chromium은 여전히 foliate-js가 WebKit 이벤트 호환을 위해 설정한 allow-scripts + allow-same-origin에 대해 샌드박스 경고를 출력하는데, 이는 알려진 업스트림 구현 안내일 뿐 책 내 스크립트 실행이 허용되었음을 의미하지 않습니다.

PDF / MinerU 상태

로컬에 있는 /Applications/MinerU.app은 네트워크 연결 Electron GUI이며 mineru CLI를 제공하지 않으므로, 현재 빌드는 /api/health에서 PDF 미활성 상태를 명시적으로 보고합니다. PDF 어댑터는 핵심 의존성 밖에 유지됩니다. 사용자가 명시적으로 구성한 로컬 CLI가 감지된 경우에만 활성화해야 하며, Python/MinerU 반복 설치나 문서의 의도치 않은 업로드를 피해야 합니다.

단계 기록 및 기술 검증은 PROGRESS.md를 참조하세요.