MCP Ebook Read

mcp电子书阅读

用于Codex读取和检索EPUB/PDF文档内容的本地MCP服务器。

一个命令Docker设置

Qdrant（必填）

docker rm -f qdrant 2>/dev/null || true && docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant:v1.18.0

GROBID（启动前和 document_ingest_pdf_paper)

docker rm -f grobid 2>/dev/null || true && docker run -d --name grobid --init --ulimit core=0 -p 8070:8070 grobid/grobid:0.9.0-crf

验证服务

curl -sS http://localhost:6333/collections
curl -sS http://localhost:8070/api/isalive

预期：

• Qdrant返回JSON "status":"ok"
• GROBID返回 true

运行MCP服务器（通过PyPI uvx)

QDRANT_URL=http://localhost:6333 GROBID_URL=http://localhost:8070 GROBID_TIMEOUT_SECONDS=120 uvx mcp-ebook-read

如果启动预执行失败，服务器将退出，并在stderr上显示一个结构化错误负载，其中包括缺少的环境变量和设置提示。

首次运行建议

在MCP客户端内配置此MCP之前，请从终端手动运行一次：

QDRANT_URL=http://localhost:6333 GROBID_URL=http://localhost:8070 GROBID_TIMEOUT_SECONDS=120 uvx mcp-ebook-read

这预先解析并对齐了运行时依赖关系，这有助于避免MCP客户端配置后长时间的首次激活延迟。

当你想刷新时 uvx 要获取最新发布的版本，请运行：

QDRANT_URL=http://localhost:6333 GROBID_URL=http://localhost:8070 GROBID_TIMEOUT_SECONDS=120 uvx mcp-ebook-read@latest

如果您通过以下方式持续安装该工具 uv tool install，使用 uv tool upgrade mcp-ebook-read 相反。

环境变量

必修的：

• QDRANT_URL （例如 http://127.0.0.1:6333)
• GROBID_URL （例如 http://127.0.0.1:8070)

可选：

• GROBID_TIMEOUT_SECONDS （默认值 20；推荐 120 对于大型论文）
• QDRANT_COLLECTION （默认值 mcp_ebook_read_chunks)
• QDRANT_TIMEOUT_SECONDS （默认值 10)
• FASTEMBED_MODEL （快速嵌入模型覆盖）
• FASTEMBED_CACHE_PATH （FastEmbed缓存根覆盖；默认为 ~/Library/Caches/mcp-ebook-read/fastembed 在macOS和 $XDG_CACHE_HOME/mcp-ebook-read/fastembed 或 ~/.cache/mcp-ebook-read/fastembed 其他地方）
• DOCLING_FORMULA_ENRICHMENT (true 默认情况下）
• PDF_FORMULA_REQUIRE_ENGINE (true 默认情况下）
• PDF_FORMULA_BATCH_SIZE (auto 默认情况下；或显式整数）
• PDF_DOCLING_NUM_THREADS （覆盖文档CPU线程）
• PDF_DOCLING_BATCH_SIZE （将文档OCR/布局/表格批量大小一起覆盖）
• PDF_DOCLING_DEVICE （例如，覆盖Docling加速器设备 auto 或 cpu)
• PDF_DOCLING_TUNING_PROFILE_PATH （覆盖本地自动调谐配置文件JSON路径）

持久性模型

• 持久性是基于sidecar的，并根据文档位置自动路由。
• 对于每个文档，MCP将状态写入 /.mcp-ebook-read/.
• 侧车包含：

- catalog.db - docs//reading/reading.md - docs//assets/... - docs//evidence/...

备注

• 使用 library_scan 发现 .pdf/.epub 根目录下的文件和寄存器更新/删除。
• 重新启动服务器后，调用 library_scan(root=...) 或 storage_list_sidecars(root=...) 在使用仅适用于以下情况的工具之前 doc_id.
• 使用 search 用于全局语义检索和 read 用于基于定位器的块窗口。
• 启动预飞行失败很快，需要配置Qdrant和GROBID并可访问。
• FastEmbed模型缓存默认为下的稳定的每用户缓存目录 mcp-ebook-read/fastembed 而不是系统临时目录。
• FastEmbed启动现在会执行有界重试，并在本地缓存损坏或暂时下载失败留下不完整的模型文件时，在重试之前清除损坏的每个模型缓存状态。
• 使用 document_ingest_pdf_book 为PDF书籍排队后台摄取作业。
• 使用 document_ingest_epub_book 为EPUB图书排队后台摄取作业。
• 使用 document_ingest_pdf_paper 为PDF论文排队后台摄取作业。文档仍然是规范的页面感知大纲；GROBID丰富了论文元数据和标题。
• 使用 document_ingest_status 轮询一个摄取作业（或文档的最新作业）的当前状态。
• 使用 document_ingest_list_jobs 检查一个文档的最近摄取作业历史记录。
• 使用 document_autotune_pdf_parser 在长时间摄取PDF之前，当您想在采样页面上对一些Docling线程/批处理配置文件进行基准测试，并为以后的运行保留最佳的本地配置文件时。
• 使用 search_in_outline_node 当您需要章节范围的检索时（建议用于阅读工作流程）。
• 使用 get_outline 在章节/公式/图像范围阅读之前获取文档大纲节点。
• 使用 read_outline_node 直接读取章节/大纲节点，无需定位器缝合。
• 使用 render_pdf_page 用于PDF证据呈现。
• PDF图像提取是按需进行的：摄取不会预提取PDF图像。
• 使用 pdf_list_images 触发/列出提取的PDF图形/表格图像（可选范围为一个轮廓节点）。
• 使用 pdf_read_image 以获得一个提取的PDF图像路径加上附近的文本上下文。
• 使用 pdf_book_list_formulas / pdf_book_read_formula 用于PDF书籍上以公式为中心的阅读。
• 使用 pdf_paper_list_formulas / pdf_paper_read_formula 用于在PDF文件上进行以公式为中心的阅读。
• 使用 epub_list_images 以列出提取的EPUB图像（可选地限定到一个轮廓节点）。
• 使用 epub_read_image 以获得一个EPUB图像路径加上附近的文本上下文。
• 使用 storage_list_sidecars 检查根目录下的sidecar持久性。
• 使用 storage_delete_document 删除一个文档的持久状态。
• 使用 storage_cleanup_sidecars 修剪缺失的文档/孤立工件并压缩目录。
• 对于大型论文，增加 GROBID_TIMEOUT_SECONDS （例如 120)以减少超时失败。
• PDF摄取现在使用混合公式管道：

- 文档结构提取 do_formula_enrichment. - Pix2Text作为主要的配方恢复引擎。 - 当公式标记存在但Pix2Text不可用时，会快速失败。

• 可选的公式环境控件：

- DOCLING_FORMULA_ENRICHMENT (true 默认情况下） - PDF_FORMULA_REQUIRE_ENGINE (true 默认情况下） - PDF_FORMULA_BATCH_SIZE (auto 默认情况下；从CPU和内存自动检测，或设置显式整数）

• 可选的文档性能控制：

- document_autotune_pdf_parser 对一个PDF的采样子集进行基准测试，并将所选配置文件写入本地JSON缓存。 - 默认情况下，调优配置文件位于 ~/Library/Caches/mcp-ebook-read/docling_pdf_tuning.json 在macOS和 $XDG_CACHE_HOME/mcp-ebook-read/docling_pdf_tuning.json （或 ~/.cache/...)其他地方。 - PDF_DOCLING_NUM_THREADS 和 PDF_DOCLING_BATCH_SIZE 当需要固定设置时，覆盖缓存的配置文件。

• 侧车清理是明确的：

- library_scan 不再触发基于阈值的自动压缩。 - 使用 storage_cleanup_sidecars(..., compact_catalog=true) 当你想要压实时。

• Ingest现在的设计是异步的：

- 这 document_ingest_* 工具提交工作并立即返回 job_id/doc_id; - 投票 document_ingest_status(doc_id=..., job_id=...) 直到 status 成为 succeeded 或 failed; - 使用 document_ingest_list_jobs(doc_id=...) 当您需要最近的历史记录或丢失最新的历史记录时 job_id.

无标签公式基准

使用您自己的非扫描PDF语料库作为无标签回归基线（无需手动注释）。

uvx mcp-ebook-formula-benchmark \
  --samples-dir /ABSOLUTE/PATH/TO/pdf-formula-benchmark-corpus \
  --passes 2 \
  --max-unresolved-rate 0.15 \
  --min-latex-valid-rate 0.85 \
  --min-stability-rate 1.0

输出是JSON，带有每个文档的度量和阈值通过/失败标志。退出代码为 0 当阈值通过时，否则 2.

无标签读取基准

使用公共/示例EPUB/PDF语料库来跟踪大纲、块、公式、图像、表格和本地搜索回放稳定性。

uvx mcp-ebook-reading-benchmark \
  --samples-dir /ABSOLUTE/PATH/TO/reading-benchmark-corpus \
  --passes 2 \
  --min-stability-rate 1.0

输出是JSON，具有每个文档的结构指标和阈值通过/失败标志。退出代码为 0 当阈值通过时，否则 2.

Claude代码MCP配置（JSON通过 uvx)

您可以在兼容Claude Code的服务器中注册此服务器 mcpServers JSON配置。

已发布的包

{
  "mcpServers": {
    "mcp-ebook-read": {
      "command": "uvx",
      "args": [
        "mcp-ebook-read"
      ],
      "env": {
        "QDRANT_URL": "http://127.0.0.1:6333",
        "QDRANT_COLLECTION": "mcp_ebook_read_chunks",
        "GROBID_URL": "http://127.0.0.1:8070",
        "GROBID_TIMEOUT_SECONDS": "120"
      }
    }
  }
}

安全说明

• 不要将真实密码、API密钥或令牌直接放在提交的JSON文件中。
• 使用环境变量或秘密管理器，并将示例值仅保留为占位符。

Codex MCP配置（TOML）

您还可以使用TOML样式在Codex中配置MCP服务器（例如在Codex MCP配置文件中）。

示例

[mcp_servers.mcp-ebook-read]
command = "uvx"
args = [ "mcp-ebook-read" ]
startup_timeout_sec = 60

[mcp_servers.mcp-ebook-read.env]
QDRANT_URL = "http://127.0.0.1:6333"
QDRANT_COLLECTION = "mcp_ebook_read_chunks"
GROBID_URL = "http://127.0.0.1:8070"
GROBID_TIMEOUT_SECONDS = "120"