Document parser

Document Parser — MinerU Integration

When to Use

• User provides a file path or URL, and asks to read/analyze/extract its content
• Common triggers: "read this", "analyze this document", "extract from", "parse this", "what's in this file"
• Covers ALL formats MinerU supports: PDF, DOCX/DOC, PPTX/PPT, XLSX/XLS, PNG, JPG, JPEG, JP2, WEBP, GIF, BMP, HTML, plus any URL

Tools

parse_documents — primary parsing tool

Converts documents into clean Markdown with:

• LaTeX for mathematical formulas
• HTML for tables
• OCR for scanned documents and images (80+ languages)
• Reading-order preserved for complex layouts

get_ocr_languages — list supported languages

Returns all OCR language codes available (en, ch, japan, korean, latin, arabic, cyrillic, devanagari, etc.). Use when unsure which language code to pass, or when the document's language is ambiguous.

Output Behavior

Single file (one item in file_sources): content returned inline in results[0].content. If the content is too large, it's saved to disk and truncated: true is set — in that case also read from results[0].extract_path.

Batch (multiple items): content saved to disk only. Results contain extract_path for each file. Use read_file to read the output Markdown.

Output directory defaults to ~/mineru-downloads. Override with OUTPUT_DIR env var in ~/.hermes/config.yaml under mcp_servers.mineru.env.OUTPUT_DIR.

Parameters

Parameter	Type	Default	Description
file_sources	string[]	required	Array of file paths or URLs to parse. E.g. ["paper.pdf", "https://arxiv.org/pdf/..."]
language	string	"ch"	Document language: en, ch, japan, korean, latin, etc.
model	string	"vlm"	vlm (high accuracy), pipeline (zero hallucination), or MinerU-HTML (web pages)
pages	string	all	Page range per file, e.g. ["1-5", "1,3,5-7"]
ocr	boolean	false	Enable OCR for scanned documents and images

Usage Examples

"Summarize this paper: https://arxiv.org/pdf/..."
→ parse_documents(file_sources=["https://arxiv.org/pdf/..."], language="en")

"Read both reference papers"
→ parse_documents(file_sources=["paper1.pdf", "paper2.pdf"], language="en", model="vlm")

"Parse scanned receipt and a Chinese document"
→ parse_documents(file_sources=["receipt.jpg", "报告.docx"], ocr=true)

"Read pages 5-8 of this PDF"
→ parse_documents(file_sources=["book.pdf"], pages=["5-8"], language="en")

"Extract this Wikipedia article as clean Markdown"
→ parse_documents(file_sources=["https://en.wikipedia.org/wiki/..."], model="MinerU-HTML", language="en")

Critical Pitfalls

1. Language defaults to Chinese. For English papers, always set language="en". Forgetting this causes OCR to misinterpret English text as Chinese characters.
2. For scanned documents and images, set ocr=true. Without it, MinerU skips OCR entirely and returns empty or garbled output.
3. Token is at /opt/data/.mineru-token and configured in ~/.hermes/config.yaml under mcp_servers.mineru.env.MINERU_API_TOKEN. Flash mode works without token but has lower limits (10MB/20 pages).

When to Load Reference Details

The MCP tool auto-selects mode: if MINERU_API_TOKEN is set (it is — configured in ~/.hermes/config.yaml), it uses Precision (vlm, higher accuracy, up to 200MB/200 pages). Without token, it falls back to flash mode.

Prefer Precision by default — our token gives 1000 pages/day high priority, and the accuracy difference matters for math-heavy papers. Only fall back to flash if:

• Token call fails (rare) → remove MINERU_API_TOKEN env to force flash
• You want instant results without API overhead → flash is faster (3-5s vs 8-12s)

Load references/integration-details.md whenever:

• Precision API returns errors → use the 5-layer diagnostic checklist
• You need to call the API directly (bypass MCP) for batch uploads or debugging
• You need to check quotas, endpoint details, or SSL workarounds

To load: skill_view(name="document-parser", file_path="references/integration-details.md") For setup details, API endpoints, free tier quotas, and the 5-layer API diagnostic checklist, see references/integration-details.md.