Skip to main content
Glama
read4all

read4all

by int2t05

read4all — 多格式附件提取 MCP Server

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 负责解析,read_markdown 负责按段直读完整解析稿

  • 产物同级目录:<附件目录>/<stem>/<stem>.md + images/,图片按 imgN.<ext> 命名(MinerU 路径细分 img/table/chart/extraN)

  • 内容哈希缓存:同文件重复转换秒级命中,文件改动自动失效

  • 图片理解:describe_images=True 为提取图生成 alt 文本,供纯文本模型"看图"

  • uvx 一键运行:Python 版 npx,uvx read4all 无需预装

Related MCP server: MinerU MCP Server

在 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 云端优先(高精度,最长等待 10 分钟,同文件有内容哈希缓存)。

3. 重启 Claude Code

重启 MCP 客户端后,先调用 convert_to_markdown 解析论文,再把返回的 md_path 交给 read_markdown 分段直读。后续段落使用上一次返回的 next_start_char,避免每轮重新解析或只读到预览。

命令行直接用(不走 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              # 跑本地和 MCP 协议测试

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

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

工具

转换、精读与能力查询共 3 个工具。深度提取能力不单独暴露,而是融入 convert 降级链:

工具

说明

引擎

get_capabilities

支持格式/引擎/MinerU 状态

—

convert_to_markdown

全格式 → Markdown + 图片(产物同级目录)

MinerU 优先 + 按格式降级

read_markdown

按字符偏移分段读取解析稿,直到全文读完

本地 Markdown

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 字符预览,用于确认解析结果)。精读通过 read_markdown(md_path, start_char, max_chars) 读取正文;每段返回 next_start_char,传入下一次调用即可继续,默认每段 12000 字符、上限 50000 字符。

MinerU 默认使用官方推荐的精准解析 API vlm,开启公式和表格识别。默认最长轮询 10 分钟;refresh_mineru=True 可跳过 read4all 本地哈希缓存并重新请求云端。无 key、无效 key、限频、超时或超出 200MB/200 页限制时按格式降级,结果含真实 engine_used 和 fallback_reason。能力查询只表示 key 已配置,不代表服务端验证通过。

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

让非多模态模型也能"看图"——为图片生成文本描述,挂为 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 单次通常需数十秒至数分钟,最长等待 10 分钟。同文件重复转换命中缓存即秒级返回(内容寻址,文件改动自动失效):

  • 缓存键 = sha1(文件内容)[:16] + 参数哈希

  • 缓存目录:~/.cache/read4all/mineru/<key>/(存 markdown.md + content_list.json + images/)

测试

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

测试夹具在 test/conftest.py 运行时生成(pymupdf 造 PDF/PNG,stdlib zipfile 造 DOCX/XLSX)。本地降级、Markdown 分段读取和缓存行为均可离线验证;云端成功路径需有效 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

贡献指南

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers