DOCSLICER_MCP_ROOT — Restrict file sources and outputs to this directory tree. Several may be given, separated by the platform path separator.
DOCSLICER_MCP_ALLOW_CLAUDE_DIR — Set to 0 to refuse documents dropped into a Claude chat, which the app copies into its own directory outside DOCSLICER_MCP_ROOT.
DOCSLICER_MCP_ALLOW_URLS — Set to 0 to reject http(s) sources and only permit local files.
Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
Lightning-fast (31 pages/sec), deterministic document parser and chunker for business documents. No LLM calls or heavy ML models.
DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, markdown and a navigable heading hierarchy.
Top score on BizDocBench (0.88 overall vs 0.70 for the next-best tool). 0.80 table accuracy, 0.98 content faithfulness, 0.85 heading recognition and hierarchy preservation, and 0.76 RAG retrieval performance.
Two ways to use it:
As a Python library — classic RAG. The layout-aware chunker gives you clean, non-overlapping chunks, each carrying its full heading breadcrumb, ready to embed. Jump to the API ↓
As an MCP server — vectorless RAG. For when you want an answer out of a document right now. Claude, Cursor, or VS Code pulls the outline, picks the section it needs, and reads only that — no embedding, and no 200-page document in the context window. Jump to setup ↓
Quick start
import docslicer
def main():
result = docslicer.parse_document("annual_report.pdf")
# Inspect the outline first
result.hierarchy.to_outline()
# - PART I — FINANCIAL INFORMATION
# - Item 1. Financial Statements
# - Notes to Condensed Consolidated Financial Statements
# - Note 4 – Financial Instruments
# - Derivative Instruments and Hedging
# - Foreign Exchange Rate Risk
# - Interest Rate Risk
# - Accounts Receivable
# - Trade Receivables
# - Item 2. Management's Discussion and Analysis
# - Liquidity and Capital Resources
# - PART II — OTHER INFORMATION
# ...
# Pull only the chunks you need
risk_section = result.find_heading("Risk Factors")[0]
chunks = result.chunks_under(risk_section)
# Tables come back structured, not as flat text
for table in result.tables_under(risk_section):
print(table.markdown)
if __name__ == "__main__":
main()
Features
No LLM, VLM, or ML models — fully deterministic; no model weights to download, no GPU required, no cold-start delay
Lightweight — ~630 KB wheel with no heavy ML dependencies
Agentic-friendly — reduces token spend on long documents: have the agent inspect the outline first, then pull only the relevant chunks into context instead of feeding a 500-page document verbatim; well-suited for legal texts, technical SOPs, financial filings, and compliance documents
Deep hierarchy extraction — works for both numbered (1., 1.2., 1.2.3) and free-form headings; uses font size, bold weight, and document structure — not inference; handles re-entry after exhibit breaks and repeated navigation headings across pages
Structure-aware chunking — splits at heading and paragraph boundaries, preserving semantic coherence
Zero character overlap — chunks are non-overlapping by default; no duplicated tokens in your context window
Unified result object — chunks, blocks, tables, charts, metadata, and hierarchy in one place
Structured tables — tables come back as cells, not flat text; export as Markdown, JSONL, or melted format
Reading order preserved — including multi-column PDF layouts
Supports pdf, docx, pptx, and html — including JS-rendered pages via Playwright
Robust URL fetching — always renders pages in a real browser, handling cookie banners and bot protection out of the box; also preserves styling signals like boldness that raw HTML omits, producing sharper heading detection and chunk quality
OCR fallback — auto-detects scanned pages and falls back to Tesseract when the extra is installed
Benchmarks
Measured with BizDocBench — an open benchmark for multi-format business document parsing. All scores are 0–1 (higher is better); pages_per_sec_aggregate is throughput across the full corpus.
Tool
Score
Coverage
Speed
Hierarchy
Faithfulness
Tables
Retrieval
Pages/sec
docslicer
0.8796
1.0000
0.8836
0.8466
0.9824
0.8047
0.7601
31.27
docling
0.7036
1.0000
0.3805
0.4905
0.8927
0.7467
0.7111
3.46
markitdown
0.5838
1.0000
0.8513
0.0604
0.7972
0.2584
0.5357
27.42
unstructured
0.5798
0.9091
0.1073
0.4327
0.9057
0.4812
0.6430
0.52
opendataloader
0.5359
0.5844
1.0000
0.3853
0.6484
0.2655
0.3317
117.26
pymupdf4llm
0.4519
0.5974
0.6492
0.1089
0.6456
0.3551
0.3552
11.84
mineru
0.4107
0.5974
0.1353
0.4220
0.6176
0.3012
0.3910
0.70
marker
0.3735
0.5974
0.1598
0.1926
0.6121
0.3012
0.3778
0.87
Install
pip install docslicer
The core install is dependency-light. Optional features are available as extras:
pip install 'docslicer[html]' # HTML / URL parsing via Playwright
playwright install chromium # one-time browser install (Chromium only)
pip install 'docslicer[ocr]' # scanned PDF support via Tesseract + OpenCV
# The tesserocr wheel bundles libtesseract but NOT the language models,
# so install the Tesseract engine to provide them (docslicer auto-detects the path):
# Linux: apt install tesseract-ocr
# macOS: brew install tesseract
pip install 'docslicer[mcp]' # MCP server for LLM clients (Claude, Cursor, …)
pip install 'docslicer[llm]' # exact token counts via tiktoken (exact_tokens=True)
pip install 'docslicer[crypto]' # password-protected Office files (msoffcrypto-tool)
pip install 'docslicer[parquet]' # Parquet export support
Extras can be combined: pip install 'docslicer[html,ocr,llm]'.
Requires Python 3.10+
What you get back (ParseResult)
parse_document returns a ParseResult:
result.chunks # list[Chunk] — heading-aware text chunks, ready for embedding
result.blocks # list[Block] — paragraph/heading/table blocks before chunking
result.tables # list[Table] — structured tables with cells, spans, and markdown
result.charts # list[Chart] — charts as extracted data points (docx/pptx)
result.metadata # DocumentMetadata — title, author, language, page count, OCR flag
result.hierarchy # HierarchyTree — navigable tree of all headings
Each Chunk carries:
chunk.text # str — chunk text
chunk.path # list — full heading breadcrumb from root to nearest heading
chunk.heading # str — nearest heading above this chunk
chunk.section # str — body | toc | exhibit | header | footer | coverpage | …
chunk.page_number # int — 1-based physical page
chunk.page_label # str — "A-6", "iv", "F-3" — as printed on the page
chunk.table_ids # list — IDs of tables referenced in this chunk
chunk.chart_ids # list — IDs of charts referenced in this chunk (docx/pptx)
chunk.link_url # list — URLs found in this chunk
chunk.bbox # BBox — bounding box (PDF only)
Every chunk carries its full heading breadcrumb, no matter how deeply nested. For example, a paragraph six levels deep in a financial filing:
This lets downstream code filter or group chunks by any level of the hierarchy without re-parsing the document.
Supported formats
Format
Extension
Notes
PDF
.pdf
Text-based and scanned (OCR extra required for scanned)
Word
.docx
Full style and outline hierarchy
HTML
.html, URLs
Static files and JS-rendered pages (html extra required for URLs)
PowerPoint
.pptx
Slides, speaker notes, charts
Not supported: .doc, .ppt (legacy Office formats), .xlsx.
Parsing
parse_document auto-detects the format from the file extension or magic bytes. Pass a file path, URL, raw bytes, or a file-like object:
result = docslicer.parse_document("contract.docx")
result = docslicer.parse_document("report.pdf")
result = docslicer.parse_document("https://www.sec.gov/Archives/edgar/data/.../10-K.htm")
result = docslicer.parse_document(file_bytes)
Parsing & content options
parse_document (and the format-specific functions) accept options that control what
gets parsed and how, before it's chunked. Format-specific toggles are accepted everywhere
for a uniform API but only take effect for the relevant format.
result = docslicer.parse_document(
"contract.docx",
password="admin123", # decrypt password-protected files; .docx and .pptx needs [crypto] extra
max_workers=4, # process-pool width for PDF extraction/OCR (default: auto by CPU cores)
include_headers_footers=True, # docx: include header/footer content (default False)
include_footnotes=True, # docx: include footnotes (default True)
include_comments=True, # docx: include review comments (default False)
include_speaker_notes=True, # pptx: include slide speaker notes (default True)
use_browser=True, # html/URL: render in a real browser (default True)
)
Because DocSlicer is structure-aware, it initially produces one chunk per heading or paragraph boundary. For documents with many short sections this can yield a lot of small chunks. With merge_small_chunks=True (the default), sibling sections under the same parent heading are merged together until they reach min_chunk_size — but never across heading boundaries into a different parent.
For example, these five short sections all fall under ## Products and Services Performance:
### Mac → "Mac net sales decreased …" (~120 chars)
### iPad → "iPad net sales increased …" (~180 chars)
### Wearables → "Wearables net sales decreased …" (~130 chars)
### Services → "Services net sales increased …" (~160 chars)
Instead of four tiny chunks, they get merged into one coherent chunk that still carries the correct path for each paragraph. Set merge_small_chunks=False if you need one chunk per section regardless of size.
Table representation formats
table_representation controls how tables are serialised into chunk text. Given a
financial table with multi-row column headers:
"markdown" (default) — preserves the original 2D layout:
Point parse_all at a folder (or pass a list of paths/URLs). It yields (source, result)
pairs, and a file that fails to parse yields the Exception instead of aborting the batch.
Any parse_document keyword — chunk sizes, include_*, etc. — is forwarded per document.
for path, result in docslicer.parse_all("documents/", recursive=True, max_chunk_size=2000):
if isinstance(result, Exception):
print(f"Failed {path}: {result}")
else:
print(f"{path}: {len(result.chunks)} chunks")
Reuse config across documents
DocumentParser holds a fixed ParseConfig across many documents and keeps a single
browser open across HTML/URL inputs (launched lazily on the first HTML parse), so a batch
of URLs starts Chromium once instead of once per document. Use it as a context manager so
that browser is always released:
from docslicer import DocumentParser, ParseConfig
config = ParseConfig(max_chunk_size=1500, optimal_chunk_size=600)
with DocumentParser(config) as parser:
for path, result in parser.parse_all(paths): # or parser.parse(path) for one
...
Two levels of parallelism
There are two independent knobs, and they compose:
ParseConfig(max_workers=N) — within a single document: parallelizes PDF word
extraction, cell building, and OCR across processes (default: auto, sized to CPU cores).
Best when documents are large.
DocumentParser(config, workers=N) — across documents: fans whole documents out
over N worker processes, each with its own config and browser. Best when you have many
documents. Results arrive in submission order (this path isn't lazy per-document).
Setting workers alone defaults each worker's max_workers to 1, so nested pools don't
oversubscribe the machine; set both explicitly to run both levels at once. The workers
path can't forward a browser session or on_stage callback across processes — leave
workers unset when you need those.
Guard your entry point. DocSlicer uses a ProcessPoolExecutor whenever there's
real CPU work to fan out — any PDF over ~50 pages, any scanned/OCR PDF of any length,
and both parallelism knobs above. This is not opt-in: a plain
docslicer.parse_document("big.pdf") triggers it too. On macOS and Windows, Python
spawns workers by re-importing your script top to bottom, so a parse that runs at module
level makes each worker re-run it and spawn again — raising RuntimeError: An attempt has been made to start a new process before the current process ... bootstrapping phase.
Put your parsing code inside a function behind an if __name__ == "__main__": guard:
def main():
with DocumentParser(config, workers=4) as parser:
for path, result in parser.parse_all(paths):
...
if __name__ == "__main__":
main()
Navigating the hierarchy
Most chunking libraries give you a flat list of text segments. DocSlicer also gives you a navigable tree of the document's heading structure, extracted deterministically from the document itself.
This is particularly useful for agents and retrieval pipelines working with long documents: rather than feeding the entire document into context, the agent can inspect the outline first to understand the structure, decide which sections are relevant, and then pull only those chunks — keeping token usage proportional to the task.
Inspect the outline
# Print the full heading tree
result.hierarchy.to_outline()
# Walk all top-level sections and see how much content each contains
for node in result.hierarchy.level(1):
print(node.text, "→", len(result.chunks_under(node)), "chunks")
Drill into a section
.level(n) returns all headings at depth n. Pass a parent to scope it to a
specific subtree — the typical pattern for an agent navigating a long document:
# All top-level headings
l1 = result.hierarchy.level(1)
# Pick one, then list its subsections
section = result.find_heading("Financial Statements")[0]
for node in result.hierarchy.level(2, parent=section):
print(node.text, f"(p.{node.page_number})")
# Drill one level deeper
subsection = result.hierarchy.level(2, parent=section)[0]
for node in result.hierarchy.level(3, parent=subsection):
print(node.text)
Retrieve content under a heading
find_heading matches any node whose text contains the search term (case-insensitive).
All retrieval methods recurse into subsections by default.
node = result.find_heading("Financial Instruments")[0]
chunks = result.chunks_under(node) # text chunks, ready for embedding or prompting
chunks = result.chunks_under(node, recursive=False) # direct heading only, no subsections
tables = result.tables_under(node) # structured tables in this section
charts = result.charts_under(node) # charts (with extracted data points) in this section
blocks = result.blocks_under(node) # raw paragraph/heading blocks
Navigate by page
result.chunks_by_page(14) # by page number
result.chunks_by_page("F-3") # by printed page label
result.blocks_by_page(14)
result.tables_by_page(14)
result.charts_by_page(14)
Parse once, navigate many times
A parsed result is plain data, so you can persist it and reload it later. When an
agent asks many questions about the same document, there's no need to parse it
again on every question:
from pathlib import Path
import docslicer
cache = Path("annual_report.json")
if cache.exists():
result = docslicer.ParseResult.load(cache)
else:
result = docslicer.parse_document("annual_report.pdf")
result.save(cache)
A reloaded result supports the full API — hierarchy, find_heading,
chunks_under, tables — so a long-running agent session or document server can
keep documents open across requests without re-parsing.
Export
save() decides what to write from the path you give it.
# Save the whole result and reload it later — keeps the heading hierarchy
result.save("result.json") # same output as result.to_json()
result = docslicer.ParseResult.load("result.json")
# A single collection, in the format you name
result.save("chunks.csv")
result.save("charts.jsonl") # stems: chunks | blocks | tables | charts | metadata
result.export_chunks_jsonl("chunks.jsonl")
# One file per collection
result.save("output/")
# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json
# (+ charts.parquet when the document has charts)
# Falls back to .csv unless the [parquet] extra is installed.
# Render as Markdown or plain text
md = result.export_to_markdown(include_tables=True)
txt = result.export_to_text()
# DataFrames
df = result.chunks_df()
Only result.json round-trips — the collection and directory forms write flat rows
without the heading hierarchy, so ParseResult.load() can't read them back.
Debug mode
result = docslicer.parse_document("report.pdf", debug=True)
# result.pipeline_steps is an ordered dict of step name → DataFrame
for name, df in result.pipeline_steps.items():
print(name, df.shape)
df.to_csv(f"debug/{name}.csv", index=False)
# PDF steps: words → shapes → cells → lines → table_cells → blocks → chunks
# DOCX/PPTX steps: runs → chart_points → paragraphs → lines → table_cells → blocks → chunks
OCR
parse_document automatically detects scanned pages and falls back to OCR when the
[ocr] extra is installed. No configuration needed — result.metadata.has_ocr
tells you whether OCR was used.
pip install 'docslicer[ocr]'
# tesserocr binds libtesseract directly, so install the Tesseract dev libraries first:
# Linux: apt install tesseract-ocr libtesseract-dev libleptonica-dev pkg-config
# macOS: brew install tesseract leptonica
MCP server
DocSlicer ships an MCP server, so LLM clients
(Claude Desktop, Claude Code, Cursor, …) can parse and read documents directly.
Download docslicer-X.Y.Z.mcpb from the
latest release and
double-click it, or drag it onto the Claude Desktop window. You pick the folder
DocSlicer is allowed to read and write during install; no config file, and no
Python of your own — uv provisions the interpreter.
Other clients
Every client below launches the server over stdio. uvx needs nothing
installed ahead of time:
If you'd rather install it once and skip the resolve on every launch, use
pip install 'docslicer[mcp]' (or uv tool install) and set
"command": "docslicer-mcp" with no args.
Client
Where the config goes
Claude Code
claude mcp add docslicer -- uvx --from 'docslicer[mcp]' docslicer-mcp
Cursor
~/.cursor/mcp.json, or .cursor/mcp.json per project
VS Code
.vscode/mcp.json (use a servers key instead of mcpServers)
Windsurf
~/.codeium/windsurf/mcp_config.json
Zed
settings.json, under context_servers
On GUI-launched clients, prefer the .mcpb. An app started from the dock
does not inherit your shell PATH — on macOS that excludes
/opt/homebrew/bin — so a bare uvx or docslicer-mcp can work in a
terminal and fail when the client spawns it. Use an absolute path
(which uvx) if you hit this. The extension sidesteps it entirely.
How it works
A parsed document is far larger than a model's context window, so the server
never returns one in a single call. parse registers the document and hands
back a doc_id handle plus a heading outline. Every other tool takes that
handle and returns a bounded slice — the model pulls in only what it needs.
Tool
Returns
parse
doc_id handle, title, page count, heading outline
get_outline
The outline again, for when it scrolls out of context
read
The text under one or more headings, named from the outline
search
Headings to read, ranked, each with a snippet
to_markdown
Writes the whole document to disk; returns the path
Every outline line carries what reading it would cost:
That figure is the same estimate read reports back, so a budget made from the
outline holds when it is spent. Sizes are cumulative — a parent never costs less
than the children beneath it — which is what makes "descend or just read it" a
decision the model can make before spending the context rather than after.
read takes heading text exactly as the outline prints it. Where a heading
appears twice, prefixing any ancestor disambiguates it ("Notes > Revenue");
the full chain is never required. Returned text is interleaved with [Page X]
markers using the document's own page labels (S-23, iv), so a quotation can
be cited to the page it actually came from rather than to wherever its section
began.
search is the fallback for when the outline does not settle the question —
headings that name nothing useful (Note 14, Item 7A), or a figure buried in
a table no heading mentions. It combines a whole-word literal match with BM25
over the chunks, and returns places, not answers: each hit is a heading to
pass to read. Query terms that appear nowhere in the document are reported
back, so a query that scored well on one rare word can be recognised as the bad
query it was.
to_markdown is the escape hatch for when the user wants the document itself
rather than an answer drawn from it. It writes to disk and returns a path, so
nothing enters the model's context and document size stops mattering.
Parsed results are cached on disk, so re-parsing the same file with the same
options is free. The cache key includes the file's size and mtime — edit the
document and the next parse re-parses it automatically.
Configuration
Variable
Effect
DOCSLICER_MCP_ROOT
Restrict file sources and written output to this directory tree. Several may be given, separated by : (; on Windows)
DOCSLICER_MCP_ALLOW_CLAUDE_DIR
Set to 0 to drop the Claude desktop app's own directory from the allowed roots (default 1)
DOCSLICER_MCP_ALLOW_URLS
Set to 0 to reject http(s) sources
DOCSLICER_MCP_CACHE
Where parsed results are persisted (default ~/.cache/docslicer-mcp)
DOCSLICER_MCP_CACHE_MAX_MB
Cache size ceiling, oldest pruned first (default 2048; 0 disables)
Set DOCSLICER_MCP_ROOT when exposing the server to anything but yourself —
without it, any readable path on the machine is parseable, and to_markdown
can write anywhere the server process can.
Documents dropped into a chat. Attaching a file to a Claude conversation
does not hand the server the path you know it by: the app first copies it into
a per-session workspace under its own data directory (~/Library/Application Support/Claude on macOS, %APPDATA%\Claude on Windows), which is nowhere near
the folder you would have picked as your root. That directory is therefore
allowed alongside DOCSLICER_MCP_ROOT, so both routes work — the folder you
chose, and whatever you drop into the chat. It is only ever added to a root
you set; leaving DOCSLICER_MCP_ROOT unset still means no sandbox at all, not
a sandbox of that one directory. Set DOCSLICER_MCP_ALLOW_CLAUDE_DIR=0 to opt
out and accept only your own roots.
to_markdown writes beside the source document, except for a document dropped
into a chat: that copy lives in a session folder you cannot navigate to, so the
markdown goes to your first DOCSLICER_MCP_ROOT instead.
Command line
docslicer parses one document to JSON on stdout — for a quick look at a file,
or to pipe into jq.
docslicer report.pdf # chunks as JSON
docslicer report.pdf -o chunks.json # write to a file
docslicer report.pdf --no-chunking # blocks instead of chunks
It takes the same parsing and chunking options as parse_document; run
docslicer --help for the full list.
Format-specific functions
If you know the format upfront and want explicit failure on unexpected input, use the
format-specific variants. They accept the same arguments as parse_document:
What is collected. Nothing. DocSlicer has no telemetry, analytics, crash
reporting, or usage tracking, and requires no account, licence key, or
registration.
How your documents are used. Parsing runs entirely on your own machine, in a
local process. Document contents are used only to produce the outline, text
slices, search results, and markdown you ask for, and are returned only to the
caller. Documents are never uploaded to DocSlicer or to any third party. When
running as an MCP server, DOCSLICER_MCP_ROOT bounds which directory tree may
be read from and written to.
Where data is stored, and for how long. Parsed results are cached on your
own disk — by default ~/.cache/docslicer-mcp, configurable with
DOCSLICER_MCP_CACHE. The cache is pruned to a size ceiling
(DOCSLICER_MCP_CACHE_MAX_MB, default 2048 MB); otherwise it persists until you
delete it, and deleting the directory removes it permanently with no copy
retained elsewhere. Nothing is written outside the cache directory and any
output path you supply.
Network access and third parties. No network request is made for a local
file. Requests leave your machine only when you pass an http(s) source: that
URL is fetched directly from the host you named, and for HTML pages Playwright
may load the subresources that page references, exactly as a browser would.
Requests to sec.gov send a User-Agent header identifying the client, as the
SEC fair-access policy requires. These hosts are third parties chosen by you,
not by DocSlicer, and their own policies govern what they log. Set
DOCSLICER_MCP_ALLOW_URLS=0 to reject remote sources entirely.
Third-party clients. When DocSlicer runs as an MCP server, the client
(Claude, Cursor, …) handles the conversation under its own privacy policy.
DocSlicer is not a party to that and receives nothing from it.
AGPL-3.0 — free to use, modify, and distribute, provided you comply with the AGPL's terms, including making the complete source of any application that uses DocSlicer available to its users (including over a network).
Commercial license — for embedding DocSlicer in a closed-source or proprietary product, or offering it as part of a hosted/SaaS service without releasing your source.
ตรวจสอบล่าสุดเมื่อ 2026-10-28 Fast, deterministic document parser and chunker for RAG and agent pipelines. Ships an MCP server for agents navigating long documents with precision.