Docling Plugin for Hivekeep

Convert documents to Markdown, JSON, and structured data using the Docling API.

Features

• Convert PDF, DOCX, PPTX, HTML, images, and more
• Output formats: Markdown, JSON, plain text, HTML
• Three tools covering the full Docling Serve v1 API:
  • convert_document — sync conversion from a URL (/v1/convert/source)
  • convert_document_file — sync conversion from an uploaded file (/v1/convert/file, multipart)
  • convert_document_async — async conversion with status polling (/v1/convert/source/async or /v1/convert/file/async → /v1/status/poll/{task_id} → /v1/result/{task_id})
• Structured results: every tool returns { status, processing_time, errors, content } so agents can inspect conversion status programmatically
• Integrates seamlessly with Hivekeep AI agents

Setup

1. Run a Docling Serve instance:

docker run -p 5001:5001 quay.io/docling-project/docling-serve

2. Install this plugin in Hivekeep (drop into plugins/docling/ or install from Git/npm).

3. Configure the plugin in Hivekeep Settings → Plugins → Docling:

   • Docling API URL (required): The base URL of your Docling Serve instance. Default: http://localhost:5001
   • API Key (optional): If your Docling Serve instance requires authentication via DOCLING_SERVE_API_KEY, enter the key here. It will be sent as the X-Api-Key header.

Usage

convert_document — sync, from URL

convert_document({
  source: "https://example.com/report.pdf",
  format: "md"
})

Parameter	Type	Description
source	string	HTTP/HTTPS URL of the document to convert
format	string	Output format: md, json, text, or html (default: md)

convert_document_file — sync, from uploaded file

convert_document_file({
  fileContent: "<base64-encoded file bytes>",
  filename: "report.pdf",
  format: "md"
})

Parameter	Type	Description
fileContent	string	Base64-encoded file content (a data: URL prefix is tolerated)
filename	string	Original filename with extension — Docling infers the input format
format	string	Output format (default: md)

The file is uploaded to /v1/convert/file as multipart/form-data with the conversion options as form fields.

convert_document_async — async with polling

convert_document_async({
  source: "https://example.com/big-report.pdf",
  format: "md",
  timeoutSeconds: 900
})

Parameter	Type	Description
source	string	HTTP/HTTPS URL of the document (provide this or fileContent + filename)
fileContent	string	Base64-encoded file content (alternative to source)
filename	string	Required when fileContent is provided
format	string	Output format (default: md)
timeoutSeconds	number	Give up after N seconds (default 600, max 3600)

The tool submits the async task, polls /v1/status/poll/{task_id} with exponential backoff (2s → 30s), then fetches the result from /v1/result/{task_id}. The returned object includes the task_id — if the tool times out, the task keeps running server-side and its result can be fetched later via GET /v1/result/{task_id}.

Result shape

All three tools return a structured object:

{
  "status": "success",
  "processing_time": 1.23,
  "errors": [],
  "content": "# Converted document …"
}

content holds the converted document in the requested format (JSON output is pretty-printed). status is one of success, partial_success, skipped, failure.

Architecture

• src/docling-api.ts — API client: all Docling Serve HTTP calls, shared types (DoclingResponse, DoclingTaskStatus), DoclingError (wraps HTTP status + response body), and the async submit → poll → fetch loop with exponential backoff.
• index.ts — thin tool registrations on top of the client.

Supported Formats

• PDF
• DOCX
• PPTX
• HTML
• Images (PNG, JPG, TIFF, BMP)
• AsciiDoc
• Markdown

License

MIT