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

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.