Read4all

PyPI Python License: MIT Tests

把 PDF / Office / 图片 / 网页文档转为 Markdown + 图片的 MCP 工具。MinerU 云端优先(高精度公式/表格/版面)+ 本地库降级(秒级,离线可用),深度提取能力(表格择优/图表几何)融入降级链,唯一转换入口。

flowchart LR
    A["附件<br/>PDF/DOCX/PPTX/XLSX/图片/HTML/..."] --> R[read4all MCP Server]
    R -->|MinerU 优先| M[MinerU 云端<br/>公式/表格/版面]
    R -->|降级| L["本地库(融入深度能力)<br/>pymupdf/pypdf/pdfplumber/MarkItDown"]
    R --> O["<附件目录>/<stem>/<stem>.md + images/"]
    M -->|内容哈希缓存| R

特性

• 全格式:PDF / DOCX / PPTX / XLSX / 图片 / HTML / EPUB / CSV / JSON / XML / TXT
• MinerU 优先 + 本地降级:有 key 走云端高精度(公式/表格/版面),无 key 自动降级本地库(秒级,功能仍可用)
• 唯一转换入口:convert_to_markdown 一个工具搞定,深度能力(表格择优、图表几何)融入降级链,不额外暴露工具
• 产物同级目录:<附件目录>/<stem>/<stem>.md + images/,图片按 imgN.<ext> 命名(MinerU 路径细分 img/table/chart/extraN)
• 内容哈希缓存:同文件重复转换秒级命中,文件改动自动失效
• 图片理解:describe_images=True 为提取图生成 alt 文本,供纯文本模型"看图"
• uvx 一键运行:Python 版 npx,uvx read4all 无需预装

在 Claude Code 中使用

1. 装 uv

uvx 是 Python 版的 npx,自动从 PyPI 拉取并运行 read4all,无需预装。先装 uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 配置 .mcp.json

在你的项目根(或 ~/.claude.json 全局)创建/编辑 .mcp.json,把 MinerU key 直接写在 env 字段:

{
  "mcpServers": {
    "read4all": {
      "command": "uvx",
      "args": ["read4all"],
      "env": {
        "MINERU_API_KEY": "你的_mineru_token"
      }
    }
  }
}

MinerU key 获取:从 https://mineru.net/apiManage 注册 → 复制 token(形如 sk-...),填入上面的 MINERU_API_KEY。

无 key 也能用:不配 env 或 key 无效时,read4all 自动降级到本地库(秒级),功能仍可用,只是 PDF 的高精度公式/表格/版面还原能力会弱些。配置后启用 MinerU 云端优先(高精度,首次 30s~3min,同文件有内容哈希缓存)。

3. 重启 Claude Code

重启后 Claude Code 会自动拉起 read4all MCP server。对它说"把这个 PDF 转成 Markdown"即可触发 convert_to_markdown 工具。

命令行直接用(不走 MCP)

uvx read4all                       # 启动 stdio server(供 MCP 客户端)
MINERU_API_KEY=你的token uvx read4all   # 带 MinerU key 启动

从源码运行(开发者)

git clone https://github.com/int2t05/read4all
cd read4all
pip install -e ".[test]"     # 可编辑安装
python -m read4all            # 启动 server
pytest test/ -v              # 跑测试(35 个真实数据测试)

源码形态的 .mcp.json(本地构建,未发布时):

{
  "mcpServers": {
    "read4all": {
      "command": "uvx", "args": ["--from", ".", "read4all"],
      "env": { "MINERU_API_KEY": "你的_mineru_token" }
    }
  }
}

工具

唯一转换入口 + 能力查询,共 2 个工具。深度提取能力不单独暴露,而是融入 convert 降级链:

工具	说明	引擎
get_capabilities	支持格式/引擎/MinerU 状态	—
convert_to_markdown	全格式 → Markdown + 图片(产物同级目录)	MinerU 优先 + 按格式降级

convert 的降级链:MinerU 优先(高精度公式/表格/版面),失败按格式降级到本地库——PDF 降级时融入深度能力(表格择优→md table、图表几何标注、嵌入图片存盘),产物更丰富;Office/网页走 MarkItDown;图片直接复制。详见 docs/TECH.md。

describe_images=True 时为提取图跑 MinerU 图片理解,文本写入 alt(供纯文本模型)。

产物契约

输入 <dir>/<stem>.<ext> → 产物落到附件同级目录:

<dir>/
├── <stem>.<ext>          ← 原附件
└── <stem>/               ← 同级产物目录
    ├── <stem>.md         ← Markdown(图片以 ![图片 img1.png](images/img1.png) 引用)
    └── images/           ← 提取图片,imgN.<ext> 命名(MinerU 路径细分 img/table/chart/extraN)

convert_to_markdown 返回 {md_path, images_dir, image_count, table_count, engine_used, fallback_reason, page_count, char_count, preview}(preview = Markdown 前 2000 字符预览,供 LLM 即用;完整内容 Read md_path)。

降级触发:MINERU_API_KEY 未设 / 401 / 429 / 超时 / >200MB 或 >200 页。结果含 engine_used + fallback_reason。

图片理解(供纯文本模型)

让非多模态模型也能"看图"——为图片生成文本描述,挂为 alt。通过 convert_to_markdown(describe_images=True) 触发:转换时为每张提取图跑 MinerU 理解,文本写入 alt(供纯文本模型)。

路径	引擎	产出	适用
首选	MinerU	图片→转 PDF→结构化 OCR 文本	文档型图片(截图/扫描/含文字图表)
扩展点	VLM	视觉大模型自然语言描述	通用图片(预留description,需配置 READ4ALL_VLM_*)
降级	—	空描述 +fallback_reason,图片仍落盘	—

VLM 语义描述扩展(可选,启用通用图片语义,同样配在 .mcp.json 的 env):

"env": {
  "MINERU_API_KEY": "你的_mineru_token",
  "READ4ALL_VLM_BASE_URL": "https://api.openai.com/v1",
  "READ4ALL_VLM_API_KEY": "你的_vlm_key",
  "READ4ALL_VLM_MODEL": "gpt-4o-mini"
}

未配置 VLM 时 description=None,MinerU 文本(文档型图片)仍可用;配置后通用图片(照片/图表)语义描述启用。

MinerU 内容哈希缓存

MinerU 单次 30s~3min。同文件重复转换命中缓存即秒级返回(内容寻址,文件改动自动失效):

• 缓存键 = sha1(文件内容)[:16] + 参数哈希
• 缓存目录:~/.cache/read4all/mineru/<key>/(存 markdown.md + content_list.json + images/)

测试

pip install -e ".[test]"
python -m pytest test/ -v

真实数据测试(无 mock):夹具在 test/conftest.py 运行时生成(pymupdf 造 PDF/PNG,stdlib zipfile 造 DOCX/XLSX)。MinerU 降级路径用真实环境(key 缺失)触发;缓存命中用预填缓存(不触网)。MinerU 成功路径需 key+网络,为手动集成测试。

能力边界

• 仅读,不做 PDF 生成/合并/拆分/表单
• 本地库不还原矢量路径公式、不做本地 OCR(均需 MinerU)
• 深度提取(表格择优/图表几何)融入 PDF 降级链,不单独暴露工具;Office/网页无此能力

文档

文档	内容
docs/TECH.md	技术文档:核心理念、模块结构、路由决策、产物契约、降级机制
docs/references/engine_benchmarks.md	三库 + MinerU 实测对照、路由依据、图表数据重建
docs/research/competitor.md	图片理解竞品调研(OCR vs VLM,三级分层方案)
docs/CHANGELOG.md	版本变更记录
docs/CONTRIBUTING.md	贡献指南