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: EPUB Reader MCP 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：書籍を開く、コンテキストを読み取る、逆方向の操作を行うスキル。

• .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フォルダは「1ファイル＝1論理章」としてインポートされ、ファイル内の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 を参照してください。