{
  "markdown": "# DocSlicer\n\n[![PyPI](https://img.shields.io/pypi/v/docslicer.svg)](https://pypi.org/project/docslicer/) [![Python versions](https://img.shields.io/pypi/pyversions/docslicer.svg)](https://pypi.org/project/docslicer/) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Commercial license available](https://img.shields.io/badge/License-Commercial-green.svg)](LICENSE-COMMERCIAL.md)\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=docslicer&config=%7B%22name%22%3A%22docslicer%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22docslicer%5Bmcp%5D%22%2C%22docslicer-mcp%22%5D%7D) [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP_server-000000?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=docslicer&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJkb2NzbGljZXJbbWNwXSIsImRvY3NsaWNlci1tY3AiXX0%3D) [![Download .mcpb for Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Download_.mcpb-D97757?logo=claude&logoColor=white)](https://github.com/DocSlicer/DocSlicer/releases/latest)\n\nLightning-fast (31 pages/sec), deterministic document parser and chunker for business documents. No LLM calls or heavy ML models.\n\nDocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, markdown and a navigable heading hierarchy.\n\nTop score on [BizDocBench](https://github.com/DocSlicer/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.\n\n**Two ways to use it:**\n\n- **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 ↓](#parsing)\n- **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 ↓](#mcp-server)\n\n### Quick start\n\n```python\nimport docslicer\n\ndef main():\n    result = docslicer.parse_document(\"annual_report.pdf\")\n\n    # Inspect the outline first\n    result.hierarchy.to_outline()\n    # - PART I — FINANCIAL INFORMATION\n    #   - Item 1. Financial Statements\n    #     - Notes to Condensed Consolidated Financial Statements\n    #       - Note 4 – Financial Instruments\n    #         - Derivative Instruments and Hedging\n    #           - Foreign Exchange Rate Risk\n    #           - Interest Rate Risk\n    #         - Accounts Receivable\n    #           - Trade Receivables\n    #   - Item 2. Management's Discussion and Analysis\n    #     - Liquidity and Capital Resources\n    # - PART II — OTHER INFORMATION\n    #   ...\n\n    # Pull only the chunks you need\n    risk_section = result.find_heading(\"Risk Factors\")[0]\n    chunks = result.chunks_under(risk_section)\n\n    # Tables come back structured, not as flat text\n    for table in result.tables_under(risk_section):\n        print(table.markdown)\n\nif __name__ == \"__main__\":\n    main()\n```\n\n---\n\n## Features\n\n- **No LLM, VLM, or ML models** — fully deterministic; no model weights to download, no GPU required, no cold-start delay\n- **Lightweight** — ~630 KB wheel with no heavy ML dependencies\n- **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\n- **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\n- **Structure-aware chunking** — splits at heading and paragraph boundaries, preserving semantic coherence\n- **Zero character overlap** — chunks are non-overlapping by default; no duplicated tokens in your context window\n- **Unified result object** — `chunks`, `blocks`, `tables`, `charts`, `metadata`, and `hierarchy` in one place\n- **Structured tables** — tables come back as cells, not flat text; export as Markdown, JSONL, or melted format\n- **Multiple export formats** — CSV, Markdown, JSONL, Parquet, JSON, plain text, and DataFrames\n- **Reading order preserved** — including multi-column PDF layouts\n- **Supports `pdf`, `docx`, `pptx`, and `html`** — including JS-rendered pages via Playwright\n- **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\n- **OCR fallback** — auto-detects scanned pages and falls back to Tesseract when the extra is installed\n\n---\n\n## Benchmarks\n\nMeasured with [BizDocBench](https://github.com/DocSlicer/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.\n\n| Tool | Score | Coverage | Speed | Hierarchy | Faithfulness | Tables | Retrieval | Pages/sec |\n|---|---|---|---|---|---|---|---|---|\n| **docslicer** | **0.8796** | 1.0000 | 0.8836 | 0.8466 | 0.9824 | 0.8047 | 0.7601 | 31.27 |\n| docling | 0.7036 | 1.0000 | 0.3805 | 0.4905 | 0.8927 | 0.7467 | 0.7111 | 3.46 |\n| markitdown | 0.5838 | 1.0000 | 0.8513 | 0.0604 | 0.7972 | 0.2584 | 0.5357 | 27.42 |\n| unstructured | 0.5798 | 0.9091 | 0.1073 | 0.4327 | 0.9057 | 0.4812 | 0.6430 | 0.52 |\n| opendataloader | 0.5359 | 0.5844 | 1.0000 | 0.3853 | 0.6484 | 0.2655 | 0.3317 | 117.26 |\n| pymupdf4llm | 0.4519 | 0.5974 | 0.6492 | 0.1089 | 0.6456 | 0.3551 | 0.3552 | 11.84 |\n| mineru | 0.4107 | 0.5974 | 0.1353 | 0.4220 | 0.6176 | 0.3012 | 0.3910 | 0.70 |\n| marker | 0.3735 | 0.5974 | 0.1598 | 0.1926 | 0.6121 | 0.3012 | 0.3778 | 0.87 |\n\n---\n\n## Install\n\n```bash\npip install docslicer\n```\n\nThe core install is dependency-light. Optional features are available as extras:\n\n```bash\npip install 'docslicer[html]'    # HTML / URL parsing via Playwright\nplaywright install chromium       # one-time browser install (Chromium only)\n\npip install 'docslicer[ocr]'     # scanned PDF support via Tesseract + OpenCV\n# The tesserocr wheel bundles libtesseract but NOT the language models,\n# so install the Tesseract engine to provide them (docslicer auto-detects the path):\n# Linux:  apt install tesseract-ocr\n# macOS:  brew install tesseract\n\npip install 'docslicer[mcp]'     # MCP server for LLM clients (Claude, Cursor, …)\npip install 'docslicer[llm]'     # exact token counts via tiktoken (exact_tokens=True)\npip install 'docslicer[crypto]'  # password-protected Office files (msoffcrypto-tool)\npip install 'docslicer[parquet]' # Parquet export support\n```\n\nExtras can be combined: `pip install 'docslicer[html,ocr,llm]'`.\n\n**Requires Python 3.10+**\n\n---\n\n## What you get back (ParseResult)\n\n`parse_document` returns a `ParseResult`:\n\n```python\nresult.chunks      # list[Chunk]   — heading-aware text chunks, ready for embedding\nresult.blocks      # list[Block]   — paragraph/heading/table blocks before chunking\nresult.tables      # list[Table]   — structured tables with cells, spans, and markdown\nresult.charts      # list[Chart]   — charts as extracted data points (docx/pptx)\nresult.metadata    # DocumentMetadata — title, author, language, page count, OCR flag\nresult.hierarchy   # HierarchyTree — navigable tree of all headings\n```\n\nEach `Chunk` carries:\n\n```python\nchunk.text          # str   — chunk text\nchunk.path          # list  — full heading breadcrumb from root to nearest heading\nchunk.heading       # str   — nearest heading above this chunk\nchunk.section       # str   — body | toc | exhibit | header | footer | coverpage | …\nchunk.page_number   # int   — 1-based physical page\nchunk.page_label    # str   — \"A-6\", \"iv\", \"F-3\" — as printed on the page\nchunk.table_ids     # list  — IDs of tables referenced in this chunk\nchunk.chart_ids     # list  — IDs of charts referenced in this chunk (docx/pptx)\nchunk.link_url      # list  — URLs found in this chunk\nchunk.bbox          # BBox  — bounding box (PDF only)\n```\n\nEvery chunk carries its full heading breadcrumb, no matter how deeply nested. For example, a paragraph six levels deep in a financial filing:\n\n```python\nchunk.path == [\n    \"# PART I — FINANCIAL INFORMATION\",\n    \"## Item 1. Financial Statements\",\n    \"### Notes to Condensed Consolidated Financial Statements (Unaudited)\",\n    \"#### Note 4 – Financial Instruments\",\n    \"##### Accounts Receivable\",\n    \"###### Trade Receivables\",\n]\n```\n\nThis lets downstream code filter or group chunks by any level of the hierarchy without re-parsing the document.\n\n---\n\n## Supported formats\n\n| Format | Extension | Notes |\n|--------|-----------|-------|\n| PDF | `.pdf` | Text-based and scanned (OCR extra required for scanned) |\n| Word | `.docx` | Full style and outline hierarchy |\n| HTML | `.html`, URLs | Static files and JS-rendered pages (html extra required for URLs) |\n| PowerPoint | `.pptx` | Slides, speaker notes, charts |\n\nNot supported: `.doc`, `.ppt` (legacy Office formats), `.xlsx`.\n\n---\n\n## Parsing\n\n`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:\n\n```python\nresult = docslicer.parse_document(\"contract.docx\")\nresult = docslicer.parse_document(\"report.pdf\")\nresult = docslicer.parse_document(\"https://www.sec.gov/Archives/edgar/data/.../10-K.htm\")\nresult = docslicer.parse_document(file_bytes)\n```\n\n### Parsing & content options\n\n`parse_document` (and the format-specific functions) accept options that control what\ngets parsed and how, before it's chunked. Format-specific toggles are accepted everywhere\nfor a uniform API but only take effect for the relevant format.\n\n```python\nresult = docslicer.parse_document(\n    \"contract.docx\",\n    password=\"admin123\",           # decrypt password-protected files; .docx and .pptx needs [crypto] extra\n    max_workers=4,                 # process-pool width for PDF extraction/OCR (default: auto by CPU cores)\n    include_headers_footers=True,  # docx: include header/footer content (default False)\n    include_footnotes=True,        # docx: include footnotes (default True)\n    include_comments=True,         # docx: include review comments (default False)\n    include_speaker_notes=True,    # pptx: include slide speaker notes (default True)\n    use_browser=True,              # html/URL: render in a real browser (default True)\n)\n```\n\n### Chunking options\n\n```python\nresult = docslicer.parse_document(\n    \"report.pdf\",\n    max_chunk_size=2000,          # hard cap, default 3200\n    optimal_chunk_size=800,       # target size, default 1500\n    min_chunk_size=400,           # soft floor, default 700\n    chunking=False,               # skip chunking, return blocks only (faster)\n    merge_small_chunks=True,      # merge chunks below min_chunk_size (default True)\n    table_representation=\"jsonl\", # \"markdown\" (default) | \"jsonl\" | \"melted\"\n    exact_tokens=True,            # exact tiktoken (cl100k_base) counts; needs [llm] extra, else char/4 estimate\n    extra_fields=[\"is_bold\", \"font_size\", \"font_name\"],  # surface internal pipeline columns on each chunk/block via .extra\n)\n```\n\n### How merge_small_chunks works\n\nBecause 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.\n\nFor example, these five short sections all fall under `## Products and Services Performance`:\n\n```\n### Mac          → \"Mac net sales decreased …\"            (~120 chars)\n### iPad         → \"iPad net sales increased …\"           (~180 chars)\n### Wearables    → \"Wearables net sales decreased …\"      (~130 chars)\n### Services     → \"Services net sales increased …\"       (~160 chars)\n```\n\nInstead 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.\n\n---\n\n### Table representation formats\n\n`table_representation` controls how tables are serialised into chunk text. Given a\nfinancial table with multi-row column headers:\n\n**`\"markdown\"` (default)** — preserves the original 2D layout:\n\n```\n|           | Three Months Ended    | Three Months Ended    |\n|           | December 27, 2025     | December 28, 2024     |\n|-----------|----------------------:|----------------------:|\n| iPhone ®  |              $85,269  |              $69,138  |\n| Mac ®     |               8,386   |               8,987   |\n| iPad ®    |               8,595   |               8,088   |\n| …         |                   …   |                   …   |\n```\n\n**`\"melted\"`** — one row per cell, headers joined with ` > `. Good for sparse or\npivot-style tables where individual cell retrieval matters:\n\n```\niPhone ® | Three Months Ended > December 27, 2025 | $85,269\niPhone ® | Three Months Ended > December 28, 2024 | $69,138\nMac ® | Three Months Ended > December 27, 2025 | 8,386\nMac ® | Three Months Ended > December 28, 2024 | 8,987\niPad ® | Three Months Ended > December 27, 2025 | 8,595\niPad ® | Three Months Ended > December 28, 2024 | 8,088\n…\n```\n\n**`\"jsonl\"`** — one JSON object per row, multi-row headers joined with `_`. Useful\nwhen chunks are fed into structured extraction or tool-use pipelines:\n\n```jsonl\n{\"Metric\": \"iPhone ®\", \"Three Months Ended_December 27, 2025\": \"$85,269\", \"Three Months Ended_December 28, 2024\": \"$69,138\"}\n{\"Metric\": \"Mac ®\", \"Three Months Ended_December 27, 2025\": \"8,386\", \"Three Months Ended_December 28, 2024\": \"8,987\"}\n{\"Metric\": \"iPad ®\", \"Three Months Ended_December 27, 2025\": \"8,595\", \"Three Months Ended_December 28, 2024\": \"8,088\"}\n…\n```\n\n### Batch processing\n\nPoint `parse_all` at a folder (or pass a list of paths/URLs). It yields `(source, result)`\npairs, and a file that fails to parse yields the `Exception` instead of aborting the batch.\nAny `parse_document` keyword — chunk sizes, `include_*`, etc. — is forwarded per document.\n\n```python\nfor path, result in docslicer.parse_all(\"documents/\", recursive=True, max_chunk_size=2000):\n    if isinstance(result, Exception):\n        print(f\"Failed {path}: {result}\")\n    else:\n        print(f\"{path}: {len(result.chunks)} chunks\")\n```\n\n### Reuse config across documents\n\n`DocumentParser` holds a fixed `ParseConfig` across many documents and keeps a single\nbrowser open across HTML/URL inputs (launched lazily on the first HTML parse), so a batch\nof URLs starts Chromium once instead of once per document. Use it as a context manager so\nthat browser is always released:\n\n```python\nfrom docslicer import DocumentParser, ParseConfig\n\nconfig = ParseConfig(max_chunk_size=1500, optimal_chunk_size=600)\n\nwith DocumentParser(config) as parser:\n    for path, result in parser.parse_all(paths):   # or parser.parse(path) for one\n        ...\n```\n\n### Two levels of parallelism\n\nThere are two independent knobs, and they compose:\n\n- **`ParseConfig(max_workers=N)`** — *within* a single document: parallelizes PDF word\n  extraction, cell building, and OCR across processes (default: auto, sized to CPU cores).\n  Best when documents are large.\n- **`DocumentParser(config, workers=N)`** — *across* documents: fans whole documents out\n  over `N` worker processes, each with its own config and browser. Best when you have many\n  documents. Results arrive in submission order (this path isn't lazy per-document).\n\nSetting `workers` alone defaults each worker's `max_workers` to `1`, so nested pools don't\noversubscribe the machine; set both explicitly to run both levels at once. The `workers`\npath can't forward a browser session or `on_stage` callback across processes — leave\n`workers` unset when you need those.\n\n> **Guard your entry point.** DocSlicer uses a `ProcessPoolExecutor` whenever there's\n> real CPU work to fan out — **any PDF over ~50 pages, any scanned/OCR PDF of any length**,\n> and both parallelism knobs above. This is not opt-in: a plain\n> `docslicer.parse_document(\"big.pdf\")` triggers it too. On macOS and Windows, Python\n> spawns workers by re-importing your script top to bottom, so a parse that runs at module\n> level makes each worker re-run it and spawn again — raising `RuntimeError: An attempt has\n> been made to start a new process before the current process ... bootstrapping phase`.\n> Put your parsing code inside a function behind an `if __name__ == \"__main__\":` guard:\n>\n> ```python\n> def main():\n>     with DocumentParser(config, workers=4) as parser:\n>         for path, result in parser.parse_all(paths):\n>             ...\n>\n> if __name__ == \"__main__\":\n>     main()\n> ```\n\n---\n\n## Navigating the hierarchy\n\nMost 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.\n\nThis 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.\n\n### Inspect the outline\n\n```python\n# Print the full heading tree\nresult.hierarchy.to_outline()\n\n# Walk all top-level sections and see how much content each contains\nfor node in result.hierarchy.level(1):\n    print(node.text, \"→\", len(result.chunks_under(node)), \"chunks\")\n```\n\n### Drill into a section\n\n`.level(n)` returns all headings at depth `n`. Pass a `parent` to scope it to a\nspecific subtree — the typical pattern for an agent navigating a long document:\n\n```python\n# All top-level headings\nl1 = result.hierarchy.level(1)\n\n# Pick one, then list its subsections\nsection = result.find_heading(\"Financial Statements\")[0]\nfor node in result.hierarchy.level(2, parent=section):\n    print(node.text, f\"(p.{node.page_number})\")\n\n# Drill one level deeper\nsubsection = result.hierarchy.level(2, parent=section)[0]\nfor node in result.hierarchy.level(3, parent=subsection):\n    print(node.text)\n```\n\n### Retrieve content under a heading\n\n`find_heading` matches any node whose text contains the search term (case-insensitive).\nAll retrieval methods recurse into subsections by default.\n\n```python\nnode = result.find_heading(\"Financial Instruments\")[0]\n\nchunks = result.chunks_under(node)              # text chunks, ready for embedding or prompting\nchunks = result.chunks_under(node, recursive=False)  # direct heading only, no subsections\ntables = result.tables_under(node)              # structured tables in this section\ncharts = result.charts_under(node)              # charts (with extracted data points) in this section\nblocks = result.blocks_under(node)              # raw paragraph/heading blocks\n```\n\n### Navigate by page\n\n```python\nresult.chunks_by_page(14)        # by page number\nresult.chunks_by_page(\"F-3\")     # by printed page label\nresult.blocks_by_page(14)\nresult.tables_by_page(14)\nresult.charts_by_page(14)\n```\n\n### Parse once, navigate many times\n\nA parsed result is plain data, so you can persist it and reload it later. When an\nagent asks many questions about the same document, there's no need to parse it\nagain on every question:\n\n```python\nfrom pathlib import Path\nimport docslicer\n\ncache = Path(\"annual_report.json\")\n\nif cache.exists():\n    result = docslicer.ParseResult.load(cache)\nelse:\n    result = docslicer.parse_document(\"annual_report.pdf\")\n    result.save(cache)\n```\n\nA reloaded result supports the full API — `hierarchy`, `find_heading`,\n`chunks_under`, `tables` — so a long-running agent session or document server can\nkeep documents open across requests without re-parsing.\n\n---\n\n## Export\n\n`save()` decides what to write from the path you give it.\n\n```python\n# Save the whole result and reload it later — keeps the heading hierarchy\nresult.save(\"result.json\")                     # same output as result.to_json()\nresult = docslicer.ParseResult.load(\"result.json\")\n\n# A single collection, in the format you name\nresult.save(\"chunks.csv\")\nresult.save(\"charts.jsonl\")       # stems: chunks | blocks | tables | charts | metadata\nresult.export_chunks_jsonl(\"chunks.jsonl\")\n\n# One file per collection\nresult.save(\"output/\")\n# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json\n#   (+ charts.parquet when the document has charts)\n#   Falls back to .csv unless the [parquet] extra is installed.\n\n# Render as Markdown or plain text\nmd = result.export_to_markdown(include_tables=True)\ntxt = result.export_to_text()\n\n# DataFrames\ndf = result.chunks_df()\n```\n\nOnly `result.json` round-trips — the collection and directory forms write flat rows\nwithout the heading hierarchy, so `ParseResult.load()` can't read them back.\n\n### Debug mode\n\n```python\nresult = docslicer.parse_document(\"report.pdf\", debug=True)\n\n# result.pipeline_steps is an ordered dict of step name → DataFrame\nfor name, df in result.pipeline_steps.items():\n    print(name, df.shape)\n    df.to_csv(f\"debug/{name}.csv\", index=False)\n\n# PDF steps:        words → shapes → cells → lines → table_cells → blocks → chunks\n# DOCX/PPTX steps:  runs → chart_points → paragraphs → lines → table_cells → blocks → chunks\n```\n\n---\n\n## OCR\n\n`parse_document` automatically detects scanned pages and falls back to OCR when the\n`[ocr]` extra is installed. No configuration needed — `result.metadata.has_ocr`\ntells you whether OCR was used.\n\n```bash\npip install 'docslicer[ocr]'\n# tesserocr binds libtesseract directly, so install the Tesseract dev libraries first:\n# Linux:  apt install tesseract-ocr libtesseract-dev libleptonica-dev pkg-config\n# macOS:  brew install tesseract leptonica\n```\n\n---\n\n## MCP server\n\nDocSlicer ships an [MCP](https://modelcontextprotocol.io) server, so LLM clients\n(Claude Desktop, Claude Code, Cursor, …) can parse and read documents directly.\n\n```bash\npip install 'docslicer[mcp]'\ndocslicer-mcp                    # stdio — what desktop clients launch\ndocslicer-mcp --transport http --port 8000\n```\n\n### Claude Desktop / Cowork — one-click install\n\nDownload `docslicer-X.Y.Z.mcpb` from the\n[latest release](https://github.com/DocSlicer/DocSlicer/releases/latest) and\ndouble-click it, or drag it onto the Claude Desktop window. You pick the folder\nDocSlicer is allowed to read and write during install; no config file, and no\nPython of your own — `uv` provisions the interpreter.\n\n### Other clients\n\nEvery client below launches the server over stdio. `uvx` needs nothing\ninstalled ahead of time:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"docslicer\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"docslicer[mcp]\", \"docslicer-mcp\"],\n      \"env\": { \"DOCSLICER_MCP_ROOT\": \"/Users/you/Documents\" }\n    }\n  }\n}\n```\n\nIf you'd rather install it once and skip the resolve on every launch, use\n`pip install 'docslicer[mcp]'` (or `uv tool install`) and set\n`\"command\": \"docslicer-mcp\"` with no `args`.\n\n| Client | Where the config goes |\n| --- | --- |\n| Claude Code | `claude mcp add docslicer -- uvx --from 'docslicer[mcp]' docslicer-mcp` |\n| Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` per project |\n| VS Code | `.vscode/mcp.json` (use a `servers` key instead of `mcpServers`) |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n| Zed | `settings.json`, under `context_servers` |\n\n> **On GUI-launched clients, prefer the `.mcpb`.** An app started from the dock\n> does not inherit your shell `PATH` — on macOS that excludes\n> `/opt/homebrew/bin` — so a bare `uvx` or `docslicer-mcp` can work in a\n> terminal and fail when the client spawns it. Use an absolute path\n> (`which uvx`) if you hit this. The extension sidesteps it entirely.\n\n### How it works\n\nA parsed document is far larger than a model's context window, so the server\nnever returns one in a single call. `parse` registers the document and hands\nback a `doc_id` handle plus a heading outline. Every other tool takes that\nhandle and returns a bounded slice — the model pulls in only what it needs.\n\n| Tool | Returns |\n| --- | --- |\n| `parse` | `doc_id` handle, title, page count, heading outline |\n| `get_outline` | The outline again, for when it scrolls out of context |\n| `read` | The text under one or more headings, named from the outline |\n| `search` | Headings to `read`, ranked, each with a snippet |\n| `to_markdown` | Writes the whole document to disk; returns the path |\n\nEvery outline line carries what reading it would cost:\n\n```\n- Financial statements  ~48k\n  - Note 14 — Segment reporting  ~900\n  - Note 15 — Income taxes  ~2.1k\n```\n\nThat figure is the same estimate `read` reports back, so a budget made from the\noutline holds when it is spent. Sizes are cumulative — a parent never costs less\nthan the children beneath it — which is what makes \"descend or just read it\" a\ndecision the model can make before spending the context rather than after.\n\n`read` takes heading text exactly as the outline prints it. Where a heading\nappears twice, prefixing any ancestor disambiguates it (`\"Notes > Revenue\"`);\nthe full chain is never required. Returned text is interleaved with `[Page X]`\nmarkers using the document's own page labels (`S-23`, `iv`), so a quotation can\nbe cited to the page it actually came from rather than to wherever its section\nbegan.\n\n`search` is the fallback for when the outline does not settle the question —\nheadings that name nothing useful (`Note 14`, `Item 7A`), or a figure buried in\na table no heading mentions. It combines a whole-word literal match with BM25\nover the chunks, and returns *places*, not answers: each hit is a heading to\npass to `read`. Query terms that appear nowhere in the document are reported\nback, so a query that scored well on one rare word can be recognised as the bad\nquery it was.\n\n`to_markdown` is the escape hatch for when the user wants the document itself\nrather than an answer drawn from it. It writes to disk and returns a path, so\nnothing enters the model's context and document size stops mattering.\n\nParsed results are cached on disk, so re-parsing the same file with the same\noptions is free. The cache key includes the file's size and mtime — edit the\ndocument and the next `parse` re-parses it automatically.\n\n### Configuration\n\n| Variable | Effect |\n| --- | --- |\n| `DOCSLICER_MCP_ROOT` | Restrict file sources **and** written output to this directory tree. Several may be given, separated by `:` (`;` on Windows) |\n| `DOCSLICER_MCP_ALLOW_CLAUDE_DIR` | Set to `0` to drop the Claude desktop app's own directory from the allowed roots (default `1`) |\n| `DOCSLICER_MCP_ALLOW_URLS` | Set to `0` to reject `http(s)` sources |\n| `DOCSLICER_MCP_CACHE` | Where parsed results are persisted (default `~/.cache/docslicer-mcp`) |\n| `DOCSLICER_MCP_CACHE_MAX_MB` | Cache size ceiling, oldest pruned first (default `2048`; `0` disables) |\n\nSet `DOCSLICER_MCP_ROOT` when exposing the server to anything but yourself —\nwithout it, any readable path on the machine is parseable, and `to_markdown`\ncan write anywhere the server process can.\n\n**Documents dropped into a chat.** Attaching a file to a Claude conversation\ndoes not hand the server the path you know it by: the app first copies it into\na per-session workspace under its own data directory (`~/Library/Application\nSupport/Claude` on macOS, `%APPDATA%\\Claude` on Windows), which is nowhere near\nthe folder you would have picked as your root. That directory is therefore\nallowed alongside `DOCSLICER_MCP_ROOT`, so both routes work — the folder you\nchose, and whatever you drop into the chat. It is only ever *added* to a root\nyou set; leaving `DOCSLICER_MCP_ROOT` unset still means no sandbox at all, not\na sandbox of that one directory. Set `DOCSLICER_MCP_ALLOW_CLAUDE_DIR=0` to opt\nout and accept only your own roots.\n\n`to_markdown` writes beside the source document, except for a document dropped\ninto a chat: that copy lives in a session folder you cannot navigate to, so the\nmarkdown goes to your first `DOCSLICER_MCP_ROOT` instead.\n\n---\n\n## Command line\n\n`docslicer` parses one document to JSON on stdout — for a quick look at a file,\nor to pipe into `jq`.\n\n```bash\ndocslicer report.pdf                   # chunks as JSON\ndocslicer report.pdf -o chunks.json    # write to a file\ndocslicer report.pdf --no-chunking     # blocks instead of chunks\n```\n\nIt takes the same parsing and chunking options as `parse_document`; run\n`docslicer --help` for the full list.\n\n---\n\n## Format-specific functions\n\nIf you know the format upfront and want explicit failure on unexpected input, use the\nformat-specific variants. They accept the same arguments as `parse_document`:\n\n```python\ndocslicer.parse_pdf(\"report.pdf\")\ndocslicer.parse_docx(\"contract.docx\")\ndocslicer.parse_pptx(\"deck.pptx\")\ndocslicer.parse_html(\"filing.html\")\n```\n\n---\n\n## Privacy Policy\n\nFull policy: <https://docslicer.ai/privacy>\n\n**What is collected.** Nothing. DocSlicer has no telemetry, analytics, crash\nreporting, or usage tracking, and requires no account, licence key, or\nregistration.\n\n**How your documents are used.** Parsing runs entirely on your own machine, in a\nlocal process. Document contents are used only to produce the outline, text\nslices, search results, and markdown you ask for, and are returned only to the\ncaller. Documents are never uploaded to DocSlicer or to any third party. When\nrunning as an MCP server, `DOCSLICER_MCP_ROOT` bounds which directory tree may\nbe read from and written to.\n\n**Where data is stored, and for how long.** Parsed results are cached on your\nown disk — by default `~/.cache/docslicer-mcp`, configurable with\n`DOCSLICER_MCP_CACHE`. The cache is pruned to a size ceiling\n(`DOCSLICER_MCP_CACHE_MAX_MB`, default 2048 MB); otherwise it persists until you\ndelete it, and deleting the directory removes it permanently with no copy\nretained elsewhere. Nothing is written outside the cache directory and any\noutput path you supply.\n\n**Network access and third parties.** No network request is made for a local\nfile. Requests leave your machine only when you pass an `http(s)` source: that\nURL is fetched directly from the host you named, and for HTML pages Playwright\nmay load the subresources that page references, exactly as a browser would.\nRequests to `sec.gov` send a `User-Agent` header identifying the client, as the\nSEC fair-access policy requires. These hosts are third parties chosen by you,\nnot by DocSlicer, and their own policies govern what they log. Set\n`DOCSLICER_MCP_ALLOW_URLS=0` to reject remote sources entirely.\n\n**Third-party clients.** When DocSlicer runs as an MCP server, the client\n(Claude, Cursor, …) handles the conversation under its own privacy policy.\nDocSlicer is not a party to that and receives nothing from it.\n\n**Contact.** Privacy questions: jelle@docslicer.ai · Issues:\n<https://github.com/DocSlicer/DocSlicer/issues>\n\n---\n\n## License\n\nDocSlicer is **dual-licensed**:\n\n- **[AGPL-3.0](LICENSE)** — 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).\n- **[Commercial license](LICENSE-COMMERCIAL.md)** — for embedding DocSlicer in a closed-source or proprietary product, or offering it as part of a hosted/SaaS service without releasing your source.\n\nSee [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md) for details, or reach out about a commercial license.\n\n---\n\n<!--\n  Ownership marker for the official MCP registry (registry.modelcontextprotocol.io).\n  The registry verifies a PyPI package by looking for this exact line in the\n  project description, which is this README — so it only takes effect once a\n  release carrying it is published. Namespace matches the GitHub org that owns\n  the repository. Leave it in place; removing it breaks re-publication.\n-->\n\nmcp-name: io.github.DocSlicer/docslicer\n",
  "bytes": 32432,
  "sha": "0f44407eb578f612e1777485c839fcd4bb750685f799daa6ecad8cdff1768eab",
  "repo_slug": "docslicer/docslicer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_docslicer_docslicer_71522af9/readme"
}