docslicer 0.2.0__tar.gz → 0.2.2__tar.gz

{docslicer-0.2.0/src/docslicer.egg-info → docslicer-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docslicer
-Version: 0.2.0
+Version: 0.2.2
 Summary: Deterministic hierarchical document parser and chunker
 Author-email: "Market Framer Inc." <jelle@docslicer.ai>
 License-Expression: AGPL-3.0-only
@@ -50,6 +50,9 @@ Provides-Extra: crypto
 Requires-Dist: msoffcrypto-tool>=5.0; extra == "crypto"
 Provides-Extra: parquet
 Requires-Dist: pyarrow>=18.0; extra == "parquet"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0; extra == "mcp"
+Requires-Dist: tiktoken>=0.10; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
@@ -57,11 +60,22 @@ Dynamic: license-file
 
 # 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)
+[![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)
 
-Lightning-fast, deterministic hierarchical document parser and chunker for business documents. No LLM calls or heavy ML models.
+[![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)
 
-DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, and a navigable heading hierarchy — preserving the document's own structure instead of guessing at it.
+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](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.
+
+**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 ↓](#parsing)
+- **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)
+
+### Quick start
 
 ```python
 import docslicer
@@ -117,6 +131,23 @@ if __name__ == "__main__":
 
 ---
 
+## Benchmarks
+
+Measured 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.
+
+| 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
 
 ```bash
@@ -135,6 +166,7 @@ pip install 'docslicer[ocr]'     # scanned PDF support via Tesseract + OpenCV
 # 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
@@ -437,22 +469,51 @@ 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:
+
+```python
+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.
+
 ```python
-# Save everything
-result.save("output/")
-# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json
-#   (+ charts.parquet when the document has charts)
+# 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")
 
-# Specific formats
+# A single collection, in the format you name
 result.save("chunks.csv")
 result.save("charts.jsonl")       # stems: chunks | blocks | tables | charts | metadata
-result.save("result.json")        # full parse result as JSON
 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()
@@ -461,6 +522,9 @@ txt = result.export_to_text()
 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
 
 ```python
@@ -492,6 +556,142 @@ pip install 'docslicer[ocr]'
 
 ---
 
+## MCP server
+
+DocSlicer ships an [MCP](https://modelcontextprotocol.io) server, so LLM clients
+(Claude Desktop, Claude Code, Cursor, …) can parse and read documents directly.
+
+```bash
+pip install 'docslicer[mcp]'
+docslicer-mcp                    # stdio — what desktop clients launch
+docslicer-mcp --transport http --port 8000
+```
+
+### Claude Desktop / Cowork — one-click install
+
+Download `docslicer-X.Y.Z.mcpb` from the
+[latest release](https://github.com/DocSlicer/DocSlicer/releases/latest) 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:
+
+```jsonc
+{
+  "mcpServers": {
+    "docslicer": {
+      "command": "uvx",
+      "args": ["--from", "docslicer[mcp]", "docslicer-mcp"],
+      "env": { "DOCSLICER_MCP_ROOT": "/Users/you/Documents" }
+    }
+  }
+}
+```
+
+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:
+
+```
+- Financial statements  ~48k
+  - Note 14 — Segment reporting  ~900
+  - Note 15 — Income taxes  ~2.1k
+```
+
+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 |
+| `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.
+
+---
+
+## Command line
+
+`docslicer` parses one document to JSON on stdout — for a quick look at a file,
+or to pipe into `jq`.
+
+```bash
+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
@@ -506,6 +706,47 @@ docslicer.parse_html("filing.html")
 
 ---
 
+## Privacy Policy
+
+Full policy: <https://docslicer.ai/privacy>
+
+**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.
+
+**Contact.** Privacy questions: jelle@docslicer.ai · Issues:
+<https://github.com/DocSlicer/DocSlicer/issues>
+
+---
+
 ## License
 
 DocSlicer is **dual-licensed**:
@@ -514,3 +755,15 @@ DocSlicer is **dual-licensed**:
 - **[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.
 
 See [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md) for details, or reach out about a commercial license.
+
+---
+
+<!--
+  Ownership marker for the official MCP registry (registry.modelcontextprotocol.io).
+  The registry verifies a PyPI package by looking for this exact line in the
+  project description, which is this README — so it only takes effect once a
+  release carrying it is published. Namespace matches the GitHub org that owns
+  the repository. Leave it in place; removing it breaks re-publication.
+-->
+
+mcp-name: io.github.DocSlicer/docslicer

{docslicer-0.2.0 → docslicer-0.2.2}/README.md

@@ -1,10 +1,21 @@
 # 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)
+[![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)
 
-Lightning-fast, deterministic hierarchical document parser and chunker for business documents. No LLM calls or heavy ML models.
+[![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)
 
-DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, and a navigable heading hierarchy — preserving the document's own structure instead of guessing at it.
+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](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.
+
+**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 ↓](#parsing)
+- **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)
+
+### Quick start
 
 ```python
 import docslicer
@@ -60,6 +71,23 @@ if __name__ == "__main__":
 
 ---
 
+## Benchmarks
+
+Measured 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.
+
+| 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
 
 ```bash
@@ -78,6 +106,7 @@ pip install 'docslicer[ocr]'     # scanned PDF support via Tesseract + OpenCV
 # 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
@@ -380,22 +409,51 @@ 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:
+
+```python
+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.
+
 ```python
-# Save everything
-result.save("output/")
-# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json
-#   (+ charts.parquet when the document has charts)
+# 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")
 
-# Specific formats
+# A single collection, in the format you name
 result.save("chunks.csv")
 result.save("charts.jsonl")       # stems: chunks | blocks | tables | charts | metadata
-result.save("result.json")        # full parse result as JSON
 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()
@@ -404,6 +462,9 @@ txt = result.export_to_text()
 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
 
 ```python
@@ -435,6 +496,142 @@ pip install 'docslicer[ocr]'
 
 ---
 
+## MCP server
+
+DocSlicer ships an [MCP](https://modelcontextprotocol.io) server, so LLM clients
+(Claude Desktop, Claude Code, Cursor, …) can parse and read documents directly.
+
+```bash
+pip install 'docslicer[mcp]'
+docslicer-mcp                    # stdio — what desktop clients launch
+docslicer-mcp --transport http --port 8000
+```
+
+### Claude Desktop / Cowork — one-click install
+
+Download `docslicer-X.Y.Z.mcpb` from the
+[latest release](https://github.com/DocSlicer/DocSlicer/releases/latest) 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:
+
+```jsonc
+{
+  "mcpServers": {
+    "docslicer": {
+      "command": "uvx",
+      "args": ["--from", "docslicer[mcp]", "docslicer-mcp"],
+      "env": { "DOCSLICER_MCP_ROOT": "/Users/you/Documents" }
+    }
+  }
+}
+```
+
+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:
+
+```
+- Financial statements  ~48k
+  - Note 14 — Segment reporting  ~900
+  - Note 15 — Income taxes  ~2.1k
+```
+
+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 |
+| `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.
+
+---
+
+## Command line
+
+`docslicer` parses one document to JSON on stdout — for a quick look at a file,
+or to pipe into `jq`.
+
+```bash
+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
@@ -449,6 +646,47 @@ docslicer.parse_html("filing.html")
 
 ---
 
+## Privacy Policy
+
+Full policy: <https://docslicer.ai/privacy>
+
+**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.
+
+**Contact.** Privacy questions: jelle@docslicer.ai · Issues:
+<https://github.com/DocSlicer/DocSlicer/issues>
+
+---
+
 ## License
 
 DocSlicer is **dual-licensed**:
@@ -457,3 +695,15 @@ DocSlicer is **dual-licensed**:
 - **[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.
 
 See [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md) for details, or reach out about a commercial license.
+
+---
+
+<!--
+  Ownership marker for the official MCP registry (registry.modelcontextprotocol.io).
+  The registry verifies a PyPI package by looking for this exact line in the
+  project description, which is this README — so it only takes effect once a
+  release carrying it is published. Namespace matches the GitHub org that owns
+  the repository. Leave it in place; removing it breaks re-publication.
+-->
+
+mcp-name: io.github.DocSlicer/docslicer