# PDF Plus Mineru

> Hybrid PDF reading, extraction, rendering, and QA workflow that combines local Python tools with MinerU MCP for complex layouts. Use when Codex needs to read PDFs, extract text or structure, render pages for visual inspection, generate PDFs, or route difficult academic/scanned/multicolumn documents through MinerU.

- Skill: `whisperas/pdf-plus-mineru` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add whisperas/pdf-plus-mineru`
- Raw SKILL.md: https://api.skillmd.com/api/skills/whisperas/pdf-plus-mineru/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: WhisperAS (https://skillmd.com/u/whisperas)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/whisperas/pdf-plus-mineru

---


# PDF Plus MinerU

Use this skill to route PDF work to the right layer instead of forcing every task through one tool.

## Workflow

1. Start with local inspection.
   - Use `scripts/inspect_pdf.py` to check page count, text coverage, and whether the file is likely scanned.
   - Treat simple text PDFs as local-first.
   - Treat two-column academic PDFs as layout-sensitive until reading order is visually or coordinate-verified.
2. Choose the parsing path.
   - Use local tools for quick extraction, page ops, image extraction, and PDF generation.
   - Use MinerU MCP when the PDF is scanned, multicolumn, table-heavy, formula-heavy, or the user wants high-quality Markdown/structured output.
3. Validate visually after meaningful output changes.
   - Render pages with `scripts/render_pdf.py`.
   - Prefer Poppler `pdftoppm`; the script falls back to `PATH` lookup and then PyMuPDF rendering.
4. Keep outputs organized.
   - Temporary renders: `./tmp/pdfs`
   - MinerU outputs: `./tmp/mineru-output`
   - Final PDFs: `./output/pdf`

## Routing Rules

- Use local tools first for:
  - merge/split/rotate
  - metadata checks
  - quick text extraction
  - image extraction
  - generating PDFs with `reportlab`
- Use MinerU MCP for:
  - scanned PDFs
  - academic papers with two-column layout
  - table-heavy reports
  - formula-rich documents
  - requests for Markdown or better reading order
- Stay local by default for sensitive/private files unless the user clearly wants MinerU.
- Use coordinate-aware extraction plus rendered-page QA for two-column manuscripts when checking references, citations, or paragraph-level diffs.

## Two-Column Academic PDFs

- Plain text extractors may interleave left and right columns. In IEEE-style PDFs, right-column reference entries can appear before or around the `REFERENCES` heading in extracted text, creating false missing-reference reports.
- For citation/reference completeness checks, compare in-text citation numbers against a rendered reference page or coordinate-aware block extraction. Do not report missing references from a text-only regex over the substring after `REFERENCES`.
- For paragraph-level comparisons, reconstruct reading order with PyMuPDF blocks or MinerU structure, then visually spot-check changed pages.
- For final submission integrity checks, always render the last page(s) and visually inspect the reference list before concluding that entries are missing or malformed.

## Local Environment

- Python: use any local interpreter with the required packages installed
- Installed libraries:
  - `pypdf`
  - `pdfplumber`
  - `pymupdf`
  - `reportlab`
  - `pillow`
  - `pdf2image`
  - `mineru-open-sdk`
- Optional tools:
  - `pdftoppm` on `PATH` for faster page rendering
  - `uvx` on `PATH` for the bundled MinerU launcher

## Commands

```powershell
python scripts/inspect_pdf.py <pdf>
python scripts/extract_text.py <pdf> -o <txt>
python scripts/render_pdf.py <pdf>
python scripts/build_demo_pdf.py
```

## MinerU MCP

- Codex MCP entrypoint is configured through:
  - `scripts/start_mineru_mcp.ps1`
- Required environment variable:
  - `MINERU_API_TOKEN`
- Do not store the token in workspace files.
- If MinerU tools are missing in the current thread after setup, restart Codex or open a fresh session.

## Quality Bar

- Do not trust text extraction alone when layout matters.
- Do not trust naive extracted-text order for two-column references; verify with rendering or coordinate-aware extraction.
- Re-render generated or modified PDFs before delivery.
- Prefer the smallest reliable tool that solves the task.