docslicer 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docslicer
-Version: 0.2.1
+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
@@ -60,7 +60,9 @@ Dynamic: license-file
 
 # DocSlicer
 
-[![PyPI](https://img.shields.io/pypi/v/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)
+[![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)
+
+[![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)
 
 Lightning-fast (31 pages/sec), deterministic document parser and chunker for business documents. No LLM calls or heavy ML models.
 
@@ -68,9 +70,12 @@ DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clea
 
 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.
 
-**Add DocSlicer to your AI pipeline:**
-- Classic RAG: the layout-aware chunker gives you clean non-overlapping chunks, each carrying its full heading breadcrumb, ready to embed.
-- Vectorless RAG: for when you want an answer out of a document right now. The agent pulls the outline, picks the section it needs, and navigates to the correct section of text without embedding the whole document
+**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
@@ -562,19 +567,49 @@ docslicer-mcp                    # stdio — what desktop clients launch
 docslicer-mcp --transport http --port 8000
 ```
 
-Register it with a client by adding to its MCP config:
+### 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": "docslicer-mcp",
+      "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
@@ -641,6 +676,22 @@ 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
@@ -655,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**:
@@ -663,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.1 → docslicer-0.2.2}/README.md

@@ -1,6 +1,8 @@
 # DocSlicer
 
-[![PyPI](https://img.shields.io/pypi/v/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)
+[![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)
+
+[![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)
 
 Lightning-fast (31 pages/sec), deterministic document parser and chunker for business documents. No LLM calls or heavy ML models.
 
@@ -8,9 +10,12 @@ DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clea
 
 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.
 
-**Add DocSlicer to your AI pipeline:**
-- Classic RAG: the layout-aware chunker gives you clean non-overlapping chunks, each carrying its full heading breadcrumb, ready to embed.
-- Vectorless RAG: for when you want an answer out of a document right now. The agent pulls the outline, picks the section it needs, and navigates to the correct section of text without embedding the whole document
+**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
@@ -502,19 +507,49 @@ docslicer-mcp                    # stdio — what desktop clients launch
 docslicer-mcp --transport http --port 8000
 ```
 
-Register it with a client by adding to its MCP config:
+### 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": "docslicer-mcp",
+      "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
@@ -581,6 +616,22 @@ 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
@@ -595,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**:
@@ -603,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

{docslicer-0.2.1 → docslicer-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docslicer"
-version = "0.2.1"
+version = "0.2.2"
 description = "Deterministic hierarchical document parser and chunker"
 readme = "README.md"
 license = "AGPL-3.0-only"

{docslicer-0.2.1 → docslicer-0.2.2}/src/docslicer/__init__.py

@@ -20,7 +20,7 @@ try:
     from importlib.metadata import version as _pkg_version
     __version__ = _pkg_version("docslicer")
 except Exception:
-    __version__ = "0.2.0"
+    __version__ = "0.2.2"
 
 from ._config import ParseConfig
 from ._result import ParseResult, Chunk, Block, Table, TableCell, Chart, ChartPoint, BBox, HierarchyNode, HierarchyTree

{docslicer-0.2.1 → docslicer-0.2.2}/src/docslicer/_orchestrator.py

@@ -306,6 +306,7 @@ def _build_blocks(df_blocks: pd.DataFrame, extra_fields: list[str] | None = None
             link_url=_str_list(row, "link_url"),
             table_ids=_str_list(row, "table_id"),
             chart_ids=_str_list(row, "chart_id"),
+            token_count=int(row.get("token_count", 0) or 0),
             extra=_extra(row, _extra_fields),
         ))
     return out

{docslicer-0.2.1 → docslicer-0.2.2}/src/docslicer/_result.py

@@ -134,6 +134,7 @@ class Block:
     link_url: list[str]                              # unique URLs found in block
     table_ids: list[str]                             # table IDs referenced in block
     chart_ids: list[str] = field(default_factory=list)  # chart IDs referenced in block (docx/pptx)
+    token_count: int = 0                             # counted like Chunk.token_count, for budgeting a read
     extra: dict = field(default_factory=dict)        # caller-requested extra fields from the pipeline df
 
     @classmethod
@@ -151,6 +152,7 @@ class Block:
             link_url=d.get("link_url", []),
             table_ids=[_norm_id(v) for v in d.get("table_ids", [])],
             chart_ids=[_norm_id(v) for v in d.get("chart_ids", [])],
+            token_count=d.get("token_count", 0),
             extra=d.get("extra", {}),
         )
 

{docslicer-0.2.1 → docslicer-0.2.2}/src/docslicer/cli.py

@@ -112,10 +112,15 @@ def main():
         print(f"Error: {exc}", file=sys.stderr)
         sys.exit(1)
 
-    out = json.dumps([c.to_dict() for c in result.chunks], indent=2)
+    # --no-chunking stops the pipeline before chunks exist, so blocks are the
+    # unit it has to return; serializing chunks regardless printed an empty
+    # list for the one flag whose whole purpose is to produce output faster.
+    records = result.blocks if args.no_chunking else result.chunks
+    label = "blocks" if args.no_chunking else "chunks"
+    out = json.dumps([r.to_dict() for r in records], indent=2)
 
     if args.output:
         Path(args.output).write_text(out, encoding="utf-8")
-        print(f"Wrote {len(result.chunks)} chunks to {args.output}")
+        print(f"Wrote {len(records)} {label} to {args.output}")
     else:
         print(out)

{docslicer-0.2.1 → docslicer-0.2.2}/src/docslicer/mcp/_store.py

@@ -21,6 +21,7 @@ from collections import OrderedDict
 from dataclasses import dataclass
 from pathlib import Path
 
+from .. import __version__
 from .._result import ParseResult
 
 _MEMORY_LIMIT = 8  # ParseResults kept hot in RAM
@@ -137,8 +138,14 @@ def resolve_output(path: str, base: Path | None = None) -> Path:
 
 
 def make_doc_id(source: str, options: dict) -> str:
-    """Stable handle for a (source, options, file-version) triple."""
-    fingerprint = {"source": source, "options": options}
+    """Stable handle for a (source, options, file-version, docslicer-version) quad.
+
+    The version is in the fingerprint because a cached parse is a snapshot of
+    what the pipeline produced at the time, fields and all. A release that adds
+    one — block token counts, say — would otherwise be served stale records
+    missing it, and a missing field reads as a zero rather than an error.
+    """
+    fingerprint = {"source": source, "options": options, "docslicer": __version__}
     if not is_url(source):
         try:
             stat = Path(source).stat()