Document Processing API¶
Document Processing Server¶
doc_processing_std_tools.document_processing
¶
Document Processing tools MCP server.
Handles reading, rendering, and inspecting various document formats (PDF, Excel, Word, PowerPoint, images). Document processing libraries are soft dependencies — tools return clear error messages if a required library is not installed. Document creation is delegated to the code execution server.
convert_document(path, to, outdir=None, page='all', overwrite=False)
¶
Convert a document to another format and save the result as a file.
Converts Office and OpenDocument files (DOCX, XLSX, PPTX, DOC, XLS, PPT,
ODT, ODS, ODP, RTF and similar) with LibreOffice headless, and writes the
output to disk. It does NOT show the result to the model: it returns the
paths of the files it wrote. To look at pages, use
read_document_pages_as_images or render_document_page instead.
to is one of: pdf, docx, xlsx, pptx, odt, ods, odp, csv, html, txt,
png, jpg.
- png / jpg write one image per page, named
<name>-p<N>.png. The document is converted to PDF first, then each page is rendered. Choose pages withpage('all', '1-3' or '2,5', 1-indexed). A PDF source can only be converted to png or jpg. - csv exports only the first sheet of a spreadsheet.
- Other targets write one file,
<name>.<to>.
Output goes next to the source file unless outdir names an existing
directory. An existing output file is never replaced unless
overwrite=True.
Requires LibreOffice in the environment (on Debian/Ubuntu:
apt-get install libreoffice-core libreoffice-writer libreoffice-calc
libreoffice-impress), or DPTTOOLS_SOFFICE_BIN pointing at
soffice. png / jpg also need pymupdf
(the [docs] extra). Each conversion times
out after DPTTOOLS_CONVERT_TIMEOUT_S seconds (default 120).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the source document. |
required |
to
|
str
|
Target format: pdf, docx, xlsx, pptx, odt, ods, odp, csv, html, txt, png or jpg. |
required |
outdir
|
str | None
|
Existing directory to write into. Defaults to the source file's directory. |
None
|
page
|
str
|
Pages to render for png / jpg: 'all', '1-5' or '1,3,7' (1-indexed). Must be 'all' for other targets. |
'all'
|
overwrite
|
bool
|
Replace output files that already exist (default False). |
False
|
Returns:
| Type | Description |
|---|---|
str
|
JSON with |
str
|
for png / jpg, the page count for pdf when pymupdf is installed, |
str
|
otherwise null) and |
str
|
|
get_file_overview(path)
¶
Return a lightweight, file-type-specific summary without full content.
Use for fast context-gathering; for full content extraction use
read_word, read_excel, read_pdf, read_powerpoint, or
read_image.
Accepted extensions:
- PDF:
.pdf - Excel:
.xlsx,.xls - Word:
.docx,.doc - PowerPoint:
.pptx,.ppt - Image:
.png,.jpg,.jpeg,.gif,.bmp,.tiff,.tif,.webp - Other: any other extension is treated as a text/JSON file (file size, line count, first/last lines preview).
The overview is customised based on the file type:
- PDF: Page count, page dimensions, text preview per page, has_images, has_tables
- Excel: Sheet names, row/column counts per sheet, column headers, sample rows
- Word: Section headings, paragraph count, table count, word count
- PowerPoint: Slide count, slide titles, speaker notes presence
- Image: Dimensions, format, color mode, file size
- Text/JSON/Other: File size, line count, first/last lines preview
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the file. |
required |
Returns:
| Type | Description |
|---|---|
str
|
JSON string with file-type-specific metadata and summary. |
get_image_metadata(path)
¶
Read image metadata (format / dimensions / file size) WITHOUT delivering the image bytes to the model.
Use this when the agent only needs to inspect the file's shape
(e.g. to decide whether to crop / resize before reading). Returns a
JSON string. For visual inspection (the agent needs to SEE the
image), use read_image instead.
Requires the Pillow library. Install the
[docs] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the image file. |
required |
Returns:
| Type | Description |
|---|---|
str
|
JSON string with keys: |
str
|
|
ocr_image(path)
¶
OCR a single raster image (PNG/JPEG/WEBP/TIFF/BMP) via LLM Whisperer.
Use this for a photo or screenshot of text. For multi-page documents use
ocr_pdf. For text already selectable in a PDF prefer read_pdf.
Requires the LLMWHISPERER_API_KEY environment variable and the
[ocr] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the image file. A single image is a single page, so
there is no |
required |
Returns:
| Type | Description |
|---|---|
str
|
The OCR-extracted text, or an actionable |
ocr_pdf(path, pages='all')
¶
OCR a scanned / image-only PDF via the LLM Whisperer API.
Use this for PDFs whose text is not selectable (scans, photos of
documents). For text-based PDFs prefer read_pdf — it is faster and
needs no API key. For a single image file (PNG/JPEG/…), use ocr_image.
Requires the LLMWHISPERER_API_KEY environment variable and the
[ocr] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the PDF file. |
required |
pages
|
str
|
Which pages to OCR — |
'all'
|
Returns:
| Type | Description |
|---|---|
str
|
Page-delimited OCR text ( |
str
|
actionable |
read_document_pages_as_images(path, pages='all', scale=2.0, max_pages=20)
¶
Render multiple pages of a PDF / DOCX / XLSX / PPTX into the model's vision context as full-resolution images.
PDF files are rendered directly via pymupdf; DOCX / XLSX / PPTX are first
converted to PDF via LibreOffice headless, then rendered. Each requested
page is delivered to the LLM as a separate MCP ImageContent block —
the model SEES every page directly. This is the vision fallback for
scanned or image/diagram-heavy documents that read_pdf /
read_word / read_excel / read_powerpoint read as near-empty.
WARNING: pages="all" on a large PDF will return one image per
page and will very likely overload the model's context window. Prefer a
bounded range (e.g. "1-10"). max_pages caps how many pages are
returned; pages beyond the cap are dropped.
Rejects image files (.png, .jpg, .gif, .bmp, .tiff, .webp). For raw
image inspection use read_image.
Images larger than DPTTOOLS_IMAGE_MAX_EDGE_PX (1568 px on the long
edge by default) or DPTTOOLS_IMAGE_MAX_MB (3 MB) are scaled down before
they are returned, so every model provider accepts them.
Requires the pymupdf library. Install the
[docs] extra.
Office files need LibreOffice in the environment (on Debian/Ubuntu:
apt-get install libreoffice-core libreoffice-writer libreoffice-calc
libreoffice-impress), or DPTTOOLS_SOFFICE_BIN pointing at
soffice.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the document file. |
required |
pages
|
str
|
Which pages to render — 'all', '1-5', or '1,3,7' (1-indexed). |
'all'
|
scale
|
float
|
Render scale factor (default 2.0 for high-DPI). |
2.0
|
max_pages
|
int
|
Maximum number of page images to return (default 20). |
20
|
Returns:
| Type | Description |
|---|---|
list[Image] | str
|
A list of MCP ImageContent blocks (one per rendered page). On error, |
list[Image] | str
|
returns a plain string starting with |
read_excel(path, sheet=None, range=None)
¶
Read Excel file content: cell values and sheet metadata.
Cells come back as the values saved in the file (the last calculated
result of a formula, not the formula itself), as strings. The first row
is returned as headers. The result also lists merged ranges and says
whether the sheet has images or charts.
Requires the openpyxl library. Install the
[docs] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the Excel file. |
required |
sheet
|
str | None
|
Specific sheet name to read (default: the sheet that was active when the file was saved). |
None
|
range
|
str | None
|
Cell range to read, e.g. 'A1:D10' (default: all data). |
None
|
Returns:
| Type | Description |
|---|---|
str
|
JSON string with sheet data. |
read_image(path)
¶
Read an image into the model's vision context.
The result is delivered to the LLM as an MCP ImageContent block —
the model SEES the image and can transcribe its text, describe its
contents, or compare it against another image. Use this tool when
the agent needs visual access to a PNG / JPEG / WEBP / GIF / BMP /
TIFF file inside the sandbox.
For dimensions / file-size / format metadata WITHOUT the image
itself (i.e. text-only inspection), use get_image_metadata.
Images larger than DPTTOOLS_IMAGE_MAX_EDGE_PX (1568 px on the long
edge by default) or DPTTOOLS_IMAGE_MAX_MB (3 MB) are scaled down before
they are returned, so every model provider accepts them.
Requires the Pillow library. Install the
[docs] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the image file. |
required |
Returns:
| Type | Description |
|---|---|
Image | str
|
An MCP ImageContent block (the LLM consumes this as vision |
Image | str
|
input). On error, returns a plain string starting with |
Image | str
|
|
read_pdf(path, pages='all', extract_tables=False)
¶
Extract text (and optionally tables) from a text-based PDF.
For scanned / image PDFs without selectable text, use ocr_pdf
instead (requires LLMWHISPERER_API_KEY).
Requires the pdfplumber library. Install the
[docs] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the PDF file. |
required |
pages
|
str
|
Which pages to read — 'all', '1-5', or '1,3,7'. |
'all'
|
extract_tables
|
bool
|
Whether to extract tables as well. |
False
|
Returns:
| Type | Description |
|---|---|
str
|
The extracted text content (and tables if requested). |
read_powerpoint(path)
¶
Read text, slide structure, and speaker notes from a .pptx file.
For Word documents use read_word; for Excel use read_excel;
for PDFs use read_pdf or ocr_pdf.
Requires the python-pptx library. Install the
[docs] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the PowerPoint file. |
required |
Returns:
| Type | Description |
|---|---|
str
|
JSON string with slide data. |
read_word(path)
¶
Read Word document content (text, headings, tables).
Requires the python-docx library. Install the
[docs] extra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the Word document. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The document content as text. |
render_document_page(path, page=1, scale=2.0)
¶
Render a single page of a PDF / DOCX / XLSX / PPTX into the model's vision context.
PDF files are rendered directly via pymupdf; DOCX / XLSX / PPTX are
first converted to PDF via LibreOffice headless, then rendered. The
result is delivered to the LLM as an MCP ImageContent block —
the model SEES the rendered page directly.
Rejects image files (.png, .jpg, .gif, .bmp, .tiff, .webp). For
raw image inspection use read_image. For image thumbnails use
image_resize.
Images larger than DPTTOOLS_IMAGE_MAX_EDGE_PX (1568 px on the long
edge by default) or DPTTOOLS_IMAGE_MAX_MB (3 MB) are scaled down before
they are returned, so every model provider accepts them.
Requires the pymupdf library. Install the
[docs] extra.
Office files need LibreOffice in the environment (on Debian/Ubuntu:
apt-get install libreoffice-core libreoffice-writer libreoffice-calc
libreoffice-impress), or DPTTOOLS_SOFFICE_BIN pointing at
soffice.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the document file. |
required |
page
|
int
|
Page number to render (1-indexed, default 1). |
1
|
scale
|
float
|
Render scale factor (default 2.0 for high-DPI). |
2.0
|
Returns:
| Type | Description |
|---|---|
Image | str
|
An MCP ImageContent block on success; an error string starting |
Image | str
|
with |
render_document_thumbnail(path, max_pages=5)
¶
Render low-resolution thumbnails for the first N pages of a PDF / DOCX / XLSX / PPTX into the model's vision context.
Uses the same conversion pipeline as render_document_page. PDF
files are rendered directly via pymupdf. DOCX / XLSX / PPTX are first
converted to PDF via LibreOffice headless. Each thumbnail is
delivered to the LLM as a separate MCP ImageContent block — the
model SEES every page in sequence and can use them for at-a-glance
inspection (e.g. picking the page to operate on).
Rejects image files. For thumbnailing an image, use
image_resize instead.
Images larger than DPTTOOLS_IMAGE_MAX_EDGE_PX (1568 px on the long
edge by default) or DPTTOOLS_IMAGE_MAX_MB (3 MB) are scaled down before
they are returned, so every model provider accepts them.
Requires the pymupdf library. Install the
[docs] extra.
Office files need LibreOffice in the environment (on Debian/Ubuntu:
apt-get install libreoffice-core libreoffice-writer libreoffice-calc
libreoffice-impress), or DPTTOOLS_SOFFICE_BIN pointing at
soffice.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the document file. |
required |
max_pages
|
int
|
Maximum number of pages to render thumbnails for (default 5). |
5
|
Returns:
| Type | Description |
|---|---|
list[Image] | str
|
A list of MCP ImageContent blocks (one per rendered page). On |
list[Image] | str
|
error, returns a plain string starting with |