PDFStruct v0.4.0

PDFStruct converts documents on your own computer. 0.4.0 makes DOCX to PDF keep the layout, reads text that earlier versions dropped without a word, and brings two fixes that were prepared as 0.3.1 (never published). Free and open source (MIT): no account, no telemetry, no usage limits.

New: DOCX to PDF keeps the layout

• When Microsoft Word (Windows) or LibreOffice is installed, PDFStruct lets that program draw the document: text boxes, headers and footers, images, fonts and columns appear as in Word.
• Without either, the PDF is the readable re-flow as before, with the warning pdf_layout_unavailable.
• Choose with --pdf-mode auto|layout|reflow on the command line, or pdf_mode in the MCP convert tool (one new optional parameter; the tool names are unchanged).
• Safe by default: each render runs in its own process with a time limit, on a private copy in a temporary folder. Word runs as a separate hidden instance with macros disabled and is never the Word you have open. The source file is never opened in place.
• Works in the portable package too (PDFStruct.exe, pdfstruct-cli.exe).

Fixes: text that was dropped is now read

• DOCX: text boxes (for example a CV sidebar), page headers and footers, form fields, fields, tracked insertions, tables inside table cells, footnotes and endnotes.
• HTML: a table inside a table cell no longer wipes the outer table; filled-in form values are read (passwords and hidden inputs stay out).
• PDF: filled-in form fields and visible free-text annotations are read after the page text.
• Comments, sticky notes and highlights are not document text; they are only counted in a warning.

Other fixes

• Writing XLSX no longer slows down with every row: a 73-page PDF with about 29,000 blocks took 277 seconds to write and now takes 2.
• A PDF page that is only a picture and on which OCR finds no text is no longer reported as read by OCR. It keeps method none with the warning no_text_found, like an image without text. Nothing is invented and the page is kept.

DOCX and HTML files (and PDFs with forms) are extracted once more on the first run because their readers changed; cached OCR work on other PDFs is kept. On Windows, pywin32 (PSF license) is now installed for the Word engine.

Which file do I need?

File	For
PDFStruct-Portable-0.4.0-win64.zip	Windows without Python: desktop window and command line. Extract completely, then run PDFStruct.exe. Unsigned, so SmartScreen may warn. No updater, no Claude integration.
PDFStruct-Windows-Setup-0.4.0.zip	Windows with Python 3.10 to 3.13: run install-windows.cmd. Includes updater and rollback. Required for Claude.
pdfstruct-0.4.0.mcpb	Claude Desktop extension (needs Windows Setup).
pdfstruct-plugin.zip	Claude Code / Cowork plugin (needs Windows Setup).
pdfstruct-skill.zip	The skill alone, only if you do not use the plugin.
pdfstruct-0.4.0-py3-none-any.whl, pdfstruct-0.4.0.tar.gz	pip install on any platform, and source.
SHA256SUMS.txt	Checksums of all files above.

Updating

• From 0.3.0: run update-windows.cmd, then restart Claude. The extension and the plugin follow the active version and need no reinstall.
• From 0.2.1: run install-windows.cmd from the 0.4.0 Setup ZIP once (the 0.2.1 updater does not accept newer versions).

Platform status

• Windows 10/11 x64: supported. Desktop window tested by hand on Windows 11. Layout rendering tested with Microsoft Word; the LibreOffice path is covered by code but was not tested on a machine with LibreOffice for this release.
• macOS, Linux: command line and MCP server covered by automated tests; desktop window not tested. OCR is not available on macOS Intel, Linux ARM64 and Windows ARM.

Full list of changes: CHANGELOG.md

PDFStruct v0.3.0

PDFStruct converts documents on your own computer. 0.3.0 adds a new workflow: turning text into a real document without a source file. File conversion, OCR, the existing commands and the five existing MCP tools are unchanged. Free and open source (MIT): no account, no telemetry, no usage limits.

New: create a document from text

• MCP tool create_document: text that Claude wrote in a conversation is saved as DOCX, PDF, HTML, Markdown or TXT on your computer. Claude gets back a status and the file paths, not the text.
• Command line: pdfstruct-create --name NOTES --format docx,pdf --content-file notes.md (or pipe the text in).
• Desktop window: a second tab, "Create from text".
• Portable package: pdfstruct-create.exe.
• Markdown becomes Word headings, real lists, real tables and monospace code. Existing files are never replaced unless you ask for it.

Fixes

• A Markdown heading with a long run of spaces no longer takes quadratic time to read.
• A heading about a page tall no longer makes the PDF writer hang.

Which file do I need?

File	For
PDFStruct-Portable-0.3.0-win64.zip	Windows without Python: desktop window and command line. Extract completely, then run PDFStruct.exe. Unsigned, so SmartScreen may warn. No updater, no Claude integration.
PDFStruct-Windows-Setup-0.3.0.zip	Windows with Python 3.10 to 3.13: run install-windows.cmd. Includes updater and rollback. Required for Claude.
pdfstruct-0.3.0.mcpb	Claude Desktop extension (needs Windows Setup).
pdfstruct-plugin.zip	Claude Code / Cowork plugin (needs Windows Setup).
pdfstruct-skill.zip	The skill alone, only if you do not use the plugin.
pdfstruct-0.3.0-py3-none-any.whl, pdfstruct-0.3.0.tar.gz	pip install on any platform, and source.
SHA256SUMS.txt	Checksums of all files above.

pdfstruct-plugin.zip and pdfstruct-skill.zip keep their fixed names because the installer and the documentation refer to them.

Updating from 0.2.1

Run install-windows.cmd from the 0.3.0 Setup ZIP once. update-windows.cmd of 0.2.1 does not accept 0.3.0 because its runtime check expects exactly five MCP tools; it leaves 0.2.1 active. Later updates are not affected. Reinstall the .mcpb or the plugin to get create_document in Claude.

Platform status

• Windows 10/11 x64: supported. Desktop window tested by hand on Windows 11.
• macOS, Linux: command line and MCP server covered by automated tests; desktop window not tested. OCR is not available on macOS Intel, Linux ARM64 and Windows ARM.

Full list of changes: CHANGELOG.md

PDFStruct v0.2.1

PDFStruct converts documents on your own computer. 0.2.1 changes how it is installed on Windows and how it connects to Claude. Conversion, the command line, the desktop window and the MCP tools are unchanged. Free and open source (MIT): no account, no telemetry, no usage limits.

Two ways to get it on Windows

Recommended Windows Setup

PDFStruct-Windows-Setup-0.2.1.zip

For:

• normal installation (needs Python 3.10 to 3.13)
• updater and rollback
• Claude Desktop
• Claude Code
• Cowork
• MCP and skill/plugin integration

Unpack it and run install-windows.cmd.

No-Python Portable

PDFStruct-Portable-0.2.1-win64.zip

For:

• the desktop window without installing Python (PDFStruct.exe)
• the command line without installing Python (pdfstruct-cli.exe)
• document conversion on your computer

Please note:

• Extract the ZIP before running; do not start the programs from inside the ZIP.
• It is large (about 325 MB, about 800 MB unpacked) because Qt and the OCR runtime are included.
• OCR models are not included and may download on first OCR use.
• The build is unsigned, so Windows SmartScreen may warn.
• Portable has no updater.
• Portable has no MCP, Claude plugin or skill integration. Claude users should use Windows Setup.

Setup and Portable are alternatives for ordinary conversion; you need only one.

New in 0.2.1

• Windows install outside any source folder. install-windows.cmd installs the release wheel into its own folder per version, %USERPROFILE%\.local\pdfstruct\v<version>, checks it (import, command line, MCP server) and only then points the stable link %USERPROFILE%\.local\pdfstruct\current at it.
• Updates you confirm. update-windows.cmd shows the active and the latest stable version and asks before it downloads. The download is verified against its SHA-256 checksum, installed next to the old version, checked, and only then made active. -Check only looks, -List shows installed versions, -Rollback goes back to the previous one, which is always kept. Nothing runs in the background.
• Claude Code / Cowork plugin (pdfstruct-plugin.zip): the skill plus the registration of the PDFStruct MCP server.
• Claude Desktop extension (pdfstruct-0.2.1.mcpb): a plain launcher, no Node layer, nothing to configure.
• One skill source. The plugin and pdfstruct-skill.zip are built from the same file. The skill is shorter and uses the MCP tools only in Claude Desktop chat.

Claude: install order

1. Install with PDFStruct-Windows-Setup-0.2.1.zip (install-windows.cmd).
2. Claude Desktop chat: install pdfstruct-0.2.1.mcpb (Settings, Extensions, Advanced settings, Install Extension).
3. Claude Code / Cowork: install pdfstruct-plugin.zip.

• The .mcpb and the plugin contain no runtime. They start current\Scripts\pdfstruct-mcp.exe, so step 1 must be done first. After a later update they need no reinstall.
• If you use the plugin, do not also upload pdfstruct-skill.zip: the plugin already contains the same skill. The skill ZIP is only for people who do not use the plugin.

Files

File	Use
PDFStruct-Windows-Setup-0.2.1.zip	Recommended: install and update scripts plus the wheel
PDFStruct-Portable-0.2.1-win64.zip	Desktop window and command line, no Python needed
pdfstruct-0.2.1.mcpb	Claude Desktop extension
pdfstruct-plugin.zip	Claude Code / Cowork plugin
pdfstruct-skill.zip	The skill alone (alternative to the plugin)
pdfstruct-0.2.1-py3-none-any.whl, pdfstruct-0.2.1.tar.gz	Python package
SHA256SUMS.txt	SHA-256 checksums of the seven files above

The portable package was added to this release after the first publication; SHA256SUMS.txt was extended by its line, and the other files are unchanged.

See the README for the quick starts.

PDFStruct v0.2.0

PDFStruct converts documents on your own computer. 0.2.0 adds more input types, PDF output, a desktop window and a local connection to Claude. Free and open source (MIT): no account, no telemetry, no usage limits.

New

• Inputs: DOCX, TXT, Markdown, HTML and images (JPG/JPEG, PNG, TIFF, BMP, WebP) next to PDF. Images go straight to OCR; multi-page TIFF and EXIF orientation are handled.
• Output: PDF as the tenth format, next to JSON, HTML, TXT, Markdown, CSV, XLSX, DOCX, JSONL and SQLite.
• Desktop window pdfstruct-gui (PySide6): drag files in, tick formats, Convert, cancel, open the output folder.
• Claude: a local MCP server (pdfstruct-mcp) and an Agent Skill. Conversions return statuses and file names, not the document content; reading is explicit and capped at 2000 characters per call.
• One engine behind terminal, window and MCP: each input is extracted once and every requested format comes from that result.
• --all-types converts every supported file in a folder (folders stay PDF-only by default).

Install

Not on PyPI yet.

pip install "pdfstruct-0.2.0-py3-none-any.whl[gui,mcp]"

Python 3.10+; the OCR packages install automatically on Windows x86_64, Linux x86_64 and macOS Apple Silicon with Python 3.9–3.13. On Windows you can also clone the repository and run setup-windows.cmd.

Then: pdfstruct-gui, or pdfstruct report.docx --format pdf, or register the MCP server with claude mcp add --scope user pdfstruct -- <path to pdfstruct-mcp>.

Assets and how far each was verified

Asset	Status
pdfstruct-0.2.0-py3-none-any.whl, pdfstruct-0.2.0.tar.gz	Test suite, OCR and all formats pass on GitHub Actions (Windows x86_64, Linux x86_64, macOS Apple Silicon, Python 3.13). Installed into a clean environment and exercised end to end on Windows 11.
pdfstruct-skill.zip	Agent Skill (instructions only). Structure checked; loaded in Claude Code.
PDFStruct-Portable-0.2.0-win64.zip	Window + command line without Python. Built and tried on one Windows 11 x64 machine only; unsigned (SmartScreen may ask once). About 800 MB unpacked. No MCP server inside.
pdfstruct-0.2.0.mcpb	Claude Desktop connector to an installed PDFStruct. Passes mcpb validate and its launcher is tested over MCP stdio, but installing it in Claude Desktop itself has not been verified. If it does not load, use the mcpServers entry from the README.
SHA256SUMS.txt	Checksums of all files above.

The desktop window was used by hand on Windows 11. On macOS and Linux it is only started without a display by CI: unverified on a real desktop. There is no macOS .app/DMG and no Windows installer.

Format limits to know

• csv and xlsx list text blocks; they are not reconstructed tables, also for DOCX/HTML tables.
• pdf from DOCX/TXT/Markdown/HTML is a readable re-flow, not the source layout. Pixel-faithful DOCX to PDF is not a goal. pdf from an image is the picture with searchable text. A PDF input is not written again as PDF.
• Image to DOCX/Markdown/HTML contains the recognised text only.
• DOCX to DOCX, Markdown to Markdown and similar round trips lose styling (reported as a warning).
• DOCX is read as one logical page; images, headers/footers and text boxes are not read.
• PDF text uses Latin fonts (incl. Turkish and German); other scripts are reported as missing glyphs.
• OCR needs an internet connection once, to download its models (about 70 MB).
• Not supported: CSV/XLSX input, legacy DOC, RTF, ODT, EPUB, PowerPoint, HEIC. OCR is unavailable on macOS Intel, Linux ARM64 and Windows ARM.

Compatibility

Existing commands and aliases behave as before. PDF outputs keep their file names and their raw JSON shape (schema 1.0); other inputs use the additive schema 1.1 and keep their extension in output names (report.docx.txt). Because the tool version is part of the extraction fingerprint, existing PDFs are extracted once more on first use.

PDFStruct v0.1.0

PDFStruct converts PDFs locally and exports structured content. Free and open source (MIT), no account, no telemetry, no usage limits.

Highlights

• Interactive pdfstruct terminal menu: run it in a folder, pick PDFs, pick formats, done
• Multi-PDF selection and multi-format selection (N PDFs x M formats, each PDF extracted once)
• Native PDF text extraction with a per-page quality score
• Automatic OCR fallback for scans and photos (PaddleOCR, CPU, in-process, models cached per user on first use)
• Output formats: JSON, HTML, TXT, Markdown, CSV, XLSX, DOCX, JSONL, SQLite
• File, folder and batch processing; non-interactive aliases pdfjson, pdfhtml, pdftxt, pdfmd, pdfcsv, pdfxlsx, pdfdocx, pdfjsonl, pdfsqlite for scripts and CI
• Idempotent: unchanged PDFs are skipped, existing raw JSON is reused for every export

Install (from this release)

pip install pdfstruct-0.1.0-py3-none-any.whl

Python 3.10+ (OCR dependencies: 3.9–3.13). Not on PyPI yet.

Verified platforms

Tests, native extraction and CPU OCR passed on GitHub Actions with Python 3.13:

• Windows x86_64 (windows-latest)
• Linux x86_64 (ubuntu-latest)
• macOS Apple Silicon arm64 (macos-latest)

Other platforms (macOS Intel, Linux arm64, Windows ARM) install and extract native text, but OCR is not available there because paddlepaddle publishes no wheels for them.

Checksums

See SHA256SUMS.txt.