Skip to main content
Glama
docling-carve

docling-carve

by markup-carve

docling-carve

Convert Docling documents to Carve with provenance, image assets, and diagnostics for content that needs review. Use the Python API, command line, HTTP, or MCP interface. All interfaces share the same exporter and report contract.

The package owns its native wrapper over carve-lang 0.1.14. It does not require carve-py or an unreleased Python binding API. Python 3.10 or newer is required.

Installation

Until wheels are published, build from this repository with Rust and Python installed:

python -m venv .venv
. .venv/bin/activate
pip install maturin
maturin develop --release

After publication, install docling-carve. The core dependency is docling-core; the full extraction pipeline is optional. Extras are extract, http, and mcp. They can be combined, for example docling-carve[http,extract].

Related MCP server: PDF MCP Server

Python

from docling_core.types.doc import DoclingDocument, DocItemLabel
from docling_carve import export_docling

doc = DoclingDocument(name="report")
doc.add_heading("Report", level=1)
doc.add_text(label=DocItemLabel.PARAGRAPH, text="Reviewed content.")
result = export_docling(doc)
print(result.value)
result.write_bundle("report-bundle")

export_json(payload) accepts a Docling JSON object, string, or bytes. CarveDocSerializer and CarveSerializerProvider implement Docling's serializer interfaces. See the API guide.

Command line

docling-carve convert document.json -o document.crv --report report.json
docling-carve convert document.json --bundle report-bundle
docling-carve batch incoming --output-dir converted --keep-going
docling-carve convert report.pdf --extract --bundle report-bundle
docling-carve convert report.pdf --extract --pdf-pipeline native --bundle native-bundle

Bundles contain document.crv, report.json, ast.json, preview.html, extracted PNG assets, and docling.json. Existing outputs are refused. --force replaces a managed bundle only when it contains no unrelated files. Use --no-source-snapshot to omit the original document.

--strict refuses any conversion diagnostic and exits with status 2. Other failures use status 1. --format selects carve, report-json, ast-json, or html. JSON reports written to stdout include base64 assets.

HTTP and MCP

docling-carve serve --host 127.0.0.1 --port 8080
docling-carve mcp
docling-carve mcp --root ./incoming

HTTP accepts Docling JSON at POST /v1/convert, and uploaded document bytes at POST /v1/extract when extraction is installed. Set DOCLING_CARVE_TOKEN to require a bearer token. MCP runs over stdio; file extraction requires an explicit root. See service examples for JavaScript, PHP, and MCP clients.

Preservation limits

Reports always set complete: false. Conversion checks reading order, nested lists, formatting, table geometry, captions, assets, and available provenance. It cannot establish extraction accuracy, preserve visual layout, or verify downstream rendering. Unsupported roles and normalizations produce diagnostics. The original Docling snapshot retains information outside the Carve mapping.

Body content is exported by default. Other layers must be selected explicitly. Image files from JSON require a contained asset_root; remote image references are rejected. Resource limits cover input bytes, document items, table cells, image pixels, asset bytes, and retained diagnostics.

See mapping and compatibility, report schema, and development and release.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Reads PDF files from local disk and returns their text and positional structure to an LLM host over stdio.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables local, read-only extraction of text and structure from PDF, DOCX, PPTX, SVG, and PNG files, including OCR for images, directory tree and metadata reporting, with strict path isolation and audit logging.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to a single directory tree over stdio, enabling list, read, search, and metadata operations with strict path containment to prevent access outside the allowed root.
      -