Skip to main content
Glama

pdf-slice

PDF → clean markdown that never silently returns wrong content.

License: MIT Python 3.10+ MCP server

A small, local, CPU-only tool that converts a PDF (file or URL) to clean markdown — and is engineered around one rule: if the output might be wrong or incomplete, it says so, loudly. No silent failures, no wrong documents, no empty results dressed up as success.

فارسی · Agent skill

Why this exists

pdf-slice is built directly from two real, silent failure modes reported against Firecrawl's PDF pipeline:

  • Cache served the wrong document — several different files that shared the name Nexus.pdf collided in the cache, so a user asking for the April report silently received the March report, with a 200 status and correct-looking metadata. pdf-slice keys its cache by full URL + SHA-256 of the downloaded bytes — never the filename — and re-verifies the content hash before serving anything from cache. A mismatch means a fresh extraction, never the wrong document.

  • White text hidden in nested forms — a 46-page PDF whose body text was white, nested inside form XObjects under an opaque image, came back as ~3,000 header-only characters while other extractors found 86,000+. The classifier had declared "text-based, confidence 1.0, no OCR needed". pdf-slice treats a suspiciously thin native extraction as a signal, not an answer: it falls back to OCR automatically and always reports which path produced the output.

Related MCP server: document-parser

What you get

  • Clean markdown with natural reading order (multi-column aware) and tables preserved as markdown tables. A table that is detected but cannot be parsed reliably produces a warning — never silent loss.

  • Provenance metadata (JSON) for every run: extraction_path (native / ocr / fallback), per-page origin, character counts, table counts and timings, content_hash, cache state (hit / miss / miss-hash-mismatch), and warnings.

  • RAG chunks (JSONL) with provenance: each chunk carries text, page, element_type (heading / paragraph / table), confidence, source (URI + content hash) and reading_order.

  • Batch mode: process a whole folder of PDFs with one command and get a summary report (files, OCR pages, warnings).

  • Loud failures: encrypted, corrupt, empty, zero-byte and non-PDF inputs fail with a clear error — never with empty "successful" output.

  • MCP server for Claude Code, Cursor and Codex, plus a ready-made agent skill (skills/pdf-slice/SKILL.md).

Install

# from source
git clone https://github.com/kamalmosadegh/pdf-slice && cd pdf-slice
python -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python extract.py --help

# or as a package (console entry points)
pip install .
pdf-slice --help

# one command, after PyPI release
uvx pdf-slice --help

Dependencies are light and CPU-only: PyMuPDF, pytesseract, Pillow and the MCP SDK. No GPU models, no API key, no paid service.

OCR uses the system tesseract binary (eng and fas supported). If it is missing, the tool continues with a loud warning and returns low-confidence output for scanned pages — never silence:

sudo apt-get install -y tesseract-ocr tesseract-ocr-fas

Usage

# one file -> markdown + JSON metadata
pdf-slice report.pdf

# a URL (cache key = full URL + content hash)
pdf-slice https://example.com/api/docs/123

# RAG chunks with provenance (JSONL, one object per line)
pdf-slice report.pdf --format jsonl
# markdown and chunks together
pdf-slice report.pdf --format both

# a whole folder + summary report
pdf-slice --batch ./pdfs --out-dir ./out

# Persian OCR
pdf-slice scanned-fa.pdf --ocr-lang eng+fas

# thresholds (defaults: 50 chars/page; 200 for pages with images)
pdf-slice scan.pdf --min-chars-per-page 80 --image-page-chars 300

Golden rule: if warnings is non-empty, read them before trusting the markdown. The fallback path means low confidence even after OCR.

Cache

  • URL key: SHA-256(full URL); cached content is served only when the stored content_hash equals the hash of the freshly downloaded bytes.

  • Local file key: SHA-256 of the file's bytes.

  • Default location: ~/.cache/pdf-slice (override with --cache-dir or the PDF_SLICE_CACHE_DIR environment variable). --no-cache disables it entirely.

MCP server & agent skill

pdf-slice-mcp   # stdio transport, for Claude Code / Cursor / Codex
  • extract_pdf(source, ocr_lang="eng") — markdown + metadata + warnings.

  • verify_pdf(source, second_source) — extracts the same document from two routes and reports a match_rate; a low rate is a loud signal that one route served different content.

  • Ready-made client configs: mcp-config-claude.json, mcp-config-cursor.json (adjust the absolute paths to your machine).

Benchmark

Measured on the fixtures bundled in tests/fixtures/, generated by tests/benchmark.py. "Silent error" = wrong or incomplete content returned with no warning. The target is zero.

File

Path

Word recovery

Seconds/page

Silent errors

white

native

100%

1.575

0

black

native

—

1.480

0

scanned

ocr

100%

2.802

0

multilingual

native

100%

1.401

0

table

native

100%

1.632

0

columns

native

—

1.452

0

large (120 pages)

native

—

0.462

0

Total silent errors: 0.

Run the full pre-delivery test matrix (26 test groups × 3 repeats — cache collisions, white text, scanned, multilingual, tables, columns, large, corrupt, encrypted, batch, MCP, clean-install and more):

python tests/test_slice.py

Deliberately out of scope

A Firecrawl clone, crawling, anti-bot infrastructure, browser rendering, pricing, SDKs — and heavy layout/formula models (UniMERNet, TableFormer and friends). pdf-slice's edge is the never silently wrong guarantee and a fast native path, not heavyweight modelling.

License

MIT — see LICENSE.

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

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI agents with comprehensive document parsing capabilities including PDF text extraction, OCR, HTML-to-markdown conversion, table extraction, and summarization, optimized for agent workflows.
      75 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Convert PDF, DOCX, HTML, and URLs into clean, LLM-ready markdown with tables preserved and boilerplate stripped, through three MCP tools (URL, local file, or raw bytes). Hosted API with no local dependencies; 50 free conversions with a self-serve key, then $0.002 per call.
      3
      43 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Turns any URL into clean markdown/JSON and converts PDF, XLSX, CSV, DOCX into text and tables. Free tier of 100 calls/day, then pay-per-call credits.
      2
      MIT