Skip to content
Back to search

pdf-slice

PDF to clean markdown that never silently returns wrong content — content-hash cache, automatic OCR fallback, per-page provenance, RAG chunks, MCP server for AI coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kamalmosadegh--pdf-slice/badge.svg)](/listings/kamalmosadegh--pdf-slice)

HTML

<a href="/listings/kamalmosadegh--pdf-slice"><img src="/api/listings/kamalmosadegh--pdf-slice/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 166 lines
  1. # pdf-slice
  2. **PDF → clean markdown that never silently returns wrong content.**
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  4. [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
  5. [![MCP server](https://img.shields.io/badge/MCP-server-purple.svg)](#mcp-server--agent-skill)
  6. A small, local, CPU-only tool that converts a PDF (file or URL) to clean
  7. markdown — and is engineered around one rule: **if the output might be
  8. wrong or incomplete, it says so, loudly.** No silent failures, no wrong
  9. documents, no empty results dressed up as success.
  10. [فارسی](README_FA.md) · [Agent skill](skills/pdf-slice/SKILL.md)
  11. ## Why this exists
  12. pdf-slice is built directly from two real, silent failure modes reported
  13. against Firecrawl's PDF pipeline:
  14. - **Cache served the wrong document** — several different files that
  15. shared the name `Nexus.pdf` collided in the cache, so a user asking for
  16. the April report silently received the March report, with a `200`
  17. status and correct-looking metadata. pdf-slice keys its cache by
  18. **full URL + SHA-256 of the downloaded bytes** — never the filename —
  19. and re-verifies the content hash before serving anything from cache. A
  20. mismatch means a fresh extraction, never the wrong document.
  21. - **White text hidden in nested forms** — a 46-page PDF whose body text
  22. was white, nested inside form XObjects under an opaque image, came back
  23. as ~3,000 header-only characters while other extractors found 86,000+.
  24. The classifier had declared "text-based, confidence 1.0, no OCR
  25. needed". pdf-slice treats a suspiciously thin native extraction as a
  26. signal, not an answer: it **falls back to OCR automatically** and
  27. always reports which path produced the output.
  28. ## What you get
  29. - **Clean markdown** with natural reading order (multi-column aware) and
  30. tables preserved as markdown tables. A table that is detected but
  31. cannot be parsed reliably produces a warning — never silent loss.
  32. - **Provenance metadata (JSON)** for every run: `extraction_path`
  33. (`native` / `ocr` / `fallback`), per-page origin, character counts,
  34. table counts and timings, `content_hash`, cache state
  35. (`hit` / `miss` / `miss-hash-mismatch`), and `warnings`.
  36. - **RAG chunks (JSONL)** with provenance: each chunk carries `text`,
  37. `page`, `element_type` (`heading` / `paragraph` / `table`),
  38. `confidence`, `source` (URI + content hash) and `reading_order`.
  39. - **Batch mode**: process a whole folder of PDFs with one command and
  40. get a summary report (files, OCR pages, warnings).
  41. - **Loud failures**: encrypted, corrupt, empty, zero-byte and non-PDF
  42. inputs fail with a clear error — never with empty "successful" output.
  43. - **MCP server** for Claude Code, Cursor and Codex, plus a ready-made
  44. **agent skill** (`skills/pdf-slice/SKILL.md`).
  45. ## Install
  46. ```bash
  47. # from source
  48. git clone https://github.com/kamalmosadegh/pdf-slice && cd pdf-slice
  49. python -m venv .venv && .venv/bin/pip install -r requirements.txt
  50. .venv/bin/python extract.py --help
  51. # or as a package (console entry points)
  52. pip install .
  53. pdf-slice --help
  54. # one command, after PyPI release
  55. uvx pdf-slice --help
  56. ```
  57. Dependencies are light and CPU-only: PyMuPDF, pytesseract, Pillow and the
  58. MCP SDK. No GPU models, no API key, no paid service.
  59. OCR uses the system `tesseract` binary (`eng` and `fas` supported). If it
  60. is missing, the tool continues with a loud warning and returns
  61. low-confidence output for scanned pages — never silence:
  62. ```bash
  63. sudo apt-get install -y tesseract-ocr tesseract-ocr-fas
  64. ```
  65. ## Usage
  66. ```bash
  67. # one file -> markdown + JSON metadata
  68. pdf-slice report.pdf
  69. # a URL (cache key = full URL + content hash)
  70. pdf-slice https://example.com/api/docs/123
  71. # RAG chunks with provenance (JSONL, one object per line)
  72. pdf-slice report.pdf --format jsonl
  73. # markdown and chunks together
  74. pdf-slice report.pdf --format both
  75. # a whole folder + summary report
  76. pdf-slice --batch ./pdfs --out-dir ./out
  77. # Persian OCR
  78. pdf-slice scanned-fa.pdf --ocr-lang eng+fas
  79. # thresholds (defaults: 50 chars/page; 200 for pages with images)
  80. pdf-slice scan.pdf --min-chars-per-page 80 --image-page-chars 300
  81. ```
  82. **Golden rule:** if `warnings` is non-empty, read them before trusting
  83. the markdown. The `fallback` path means low confidence even after OCR.
  84. ## Cache
  85. - URL key: `SHA-256(full URL)`; cached content is served only when the
  86. stored `content_hash` equals the hash of the freshly downloaded bytes.
  87. - Local file key: `SHA-256` of the file's bytes.
  88. - Default location: `~/.cache/pdf-slice` (override with `--cache-dir` or
  89. the `PDF_SLICE_CACHE_DIR` environment variable). `--no-cache` disables
  90. it entirely.
  91. ## MCP server & agent skill
  92. ```bash
  93. pdf-slice-mcp # stdio transport, for Claude Code / Cursor / Codex
  94. ```
  95. - `extract_pdf(source, ocr_lang="eng")` — markdown + metadata + warnings.
  96. - `verify_pdf(source, second_source)` — extracts the same document from
  97. two routes and reports a `match_rate`; a low rate is a loud signal that
  98. one route served different content.
  99. - Ready-made client configs: `mcp-config-claude.json`,
  100. `mcp-config-cursor.json` (adjust the absolute paths to your machine).
  101. ## Benchmark
  102. Measured on the fixtures bundled in `tests/fixtures/`, generated by
  103. `tests/benchmark.py`. "Silent error" = wrong or incomplete content
  104. returned with no warning. The target is zero.
  105. | File | Path | Word recovery | Seconds/page | Silent errors |
  106. |---|---|---|---|---|
  107. | white | native | 100% | 1.575 | 0 |
  108. | black | native | — | 1.480 | 0 |
  109. | scanned | ocr | 100% | 2.802 | 0 |
  110. | multilingual | native | 100% | 1.401 | 0 |
  111. | table | native | 100% | 1.632 | 0 |
  112. | columns | native | — | 1.452 | 0 |
  113. | large (120 pages) | native | — | 0.462 | 0 |
  114. **Total silent errors: 0.**
  115. Run the full pre-delivery test matrix (26 test groups × 3 repeats —
  116. cache collisions, white text, scanned, multilingual, tables, columns,
  117. large, corrupt, encrypted, batch, MCP, clean-install and more):
  118. ```bash
  119. python tests/test_slice.py
  120. ```
  121. ## Deliberately out of scope
  122. A Firecrawl clone, crawling, anti-bot infrastructure, browser rendering,
  123. pricing, SDKs — and heavy layout/formula models (UniMERNet, TableFormer
  124. and friends). pdf-slice's edge is the *never silently wrong* guarantee
  125. and a fast native path, not heavyweight modelling.
  126. ## License
  127. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.