# read4all — 多格式附件提取 MCP Server

[![PyPI](https://img.shields.io/pypi/v/read4all?label=pypi)](https://pypi.org/project/read4all/)
[![Python](https://img.shields.io/pypi/pyversions/read4all)](https://pypi.org/project/read4all/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-35%20passed-brightgreen)](test/)

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

```mermaid
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](https://docs.astral.sh/uv/):

```bash
# 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` 字段:

```json
{
  "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)

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

## 从源码运行(开发者)

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

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

```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](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`):

```json
"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/`)

## 测试

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