ExStruct — Excel Structured Extraction Engine

ExStruct reads Excel workbooks into structured data and applies patch-based editing workflows through a shared core. It provides extraction APIs, a JSON-first editing CLI, and an MCP server for host-managed integrations, with options tuned for LLM/RAG preprocessing, reviewable edit flows, and local automation.

• In COM/Excel environments (Windows), it performs rich extraction.
• In non-COM environments (Linux/macOS):
  • direct OOXML parsing extracts cells, shapes, charts, table candidates, and print areas on a best-effort basis
  • if the LibreOffice runtime is available, cells, table candidates, shapes, and charts are also extracted on a best-effort basis

Detection heuristics, editing workflows, and output modes are adjustable for LLM/RAG pipelines and local automation.

Main Features

• Excel -> structured JSON: outputs cells, shapes, charts, SmartArt, table candidates, merged-cell ranges, print areas, and auto page-break areas by sheet or by area.
• Output modes:
  • light: cells + table candidates + print areas + shapes/charts (best-effort via direct OOXML parsing)
  • libreoffice: best-effort non-COM mode for .xlsx/.xlsm. When the LibreOffice runtime is available, it adds merged cells, shapes, connectors, and charts
  • standard: Excel COM mode with texted shapes + arrows, charts, SmartArt, and merged-cell ranges
  • verbose: outputs all shapes with width/height and also emits cell hyperlinks
• Formula extraction: emits formulas_map (formula string -> cell coordinates) via openpyxl/COM. It is enabled by default in verbose and can be controlled with include_formulas_map.
• Formats: JSON (compact by default, --pretty for formatting), YAML, and TOON (optional dependencies).
• Workbook editing interfaces: use the editing CLI for primary ExStruct edit flows, keep MCP for host-owned safety controls, and use exstruct.edit only when you need the same patch contract from Python.
• Table detection tuning: heuristics can be adjusted dynamically through the API.
• Hyperlink extraction: in verbose mode, or with include_cell_links=True, cell links are emitted in links.
• Safe fallback: if Excel COM or the LibreOffice runtime is unavailable, the process does not crash and falls back to direct OOXML parsing.

Installation

pip install exstruct

Optional extras:

• YAML: pip install pyyaml
• TOON: pip install python-toon
• Rendering (PDF/PNG): Excel + pip install pypdfium2 pillow (mode=libreoffice is not supported)
• Install everything at once: pip install exstruct[yaml,toon,render]

Platform note:

• On Debian/Ubuntu/WSL, install LibreOffice together with python3-uno. ExStruct probes a compatible system Python automatically for mode=libreoffice; if your environment needs an explicit interpreter, set EXSTRUCT_LIBREOFFICE_PYTHON_PATH=/usr/bin/python3.
• LibreOffice Python detection now runs the bundled bridge in --probe mode before selection. An incompatible EXSTRUCT_LIBREOFFICE_PYTHON_PATH fails fast instead of surfacing a delayed bridge SyntaxError during extraction.
• If the isolated temporary LibreOffice profile fails before the UNO socket becomes ready, ExStruct retries once with the shared/default LibreOffice profile as a compatibility fallback and reports per-attempt startup detail if both launches fail.

Quick Start CLI

exstruct input.xlsx > output.json          # compact JSON to stdout by default
exstruct input.xlsx -o out.json --pretty   # write pretty JSON to a file
exstruct input.xlsx --format yaml          # YAML (requires pyyaml)
exstruct input.xlsx --format toon          # TOON (requires python-toon)
exstruct input.xlsx --sheets-dir sheets/   # write one file per sheet
exstruct input.xlsx --auto-page-breaks-dir auto_areas/  # always shown; execution requires standard/verbose + Excel COM
exstruct input.xlsx --alpha-col            # output column keys as A, B, ..., AA
exstruct input.xlsx --include-backend-metadata  # include shape/chart backend metadata
exstruct input.xlsx --mode light           # cells + table candidates + best-effort OOXML shapes/charts
exstruct input.xlsx --mode libreoffice     # best-effort extraction of shapes/connectors/charts without COM
exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel COM required)

Auto page-break export is available from both the API and the CLI when Excel/COM is available. The CLI always exposes --auto-page-breaks-dir, but validates it at execution time. mode=libreoffice rejects --pdf, --image, and --auto-page-breaks-dir early, and mode=light also rejects --auto-page-breaks-dir. Use standard or verbose with Excel COM for those features. By default, the CLI keeps legacy 0-based numeric string column keys ("0", "1", ...). Use --alpha-col when you need Excel-style keys ("A", "B", ...). By default, serialized shape/chart output omits backend metadata (provenance, approximation_level, confidence) to reduce token usage. Use --include-backend-metadata or the corresponding Python/MCP option when you need it.

Quick Start Editing CLI

exstruct patch --input book.xlsx --ops ops.json --backend openpyxl
exstruct patch --input book.xlsx --ops - --dry-run --pretty < ops.json
exstruct make --output new.xlsx --ops ops.json --backend openpyxl
exstruct ops list
exstruct ops describe create_chart --pretty
exstruct validate --input book.xlsx --pretty

• patch and make print JSON PatchResult to stdout.
• ops list / ops describe expose the public patch-op schema.
• validate reports workbook readability (is_readable, warnings, errors).

Recommended edit flow:

1. Build patch ops.
2. Run exstruct patch --dry-run and inspect PatchResult, warnings, and diff.
3. Pin --backend openpyxl when you want the dry run and the real apply to use the same engine.
4. If you keep --backend auto, inspect PatchResult.engine; on Windows/Excel hosts the real apply may switch to COM.
5. Re-run without --dry-run only after the result is acceptable.

ExStruct CLI Skill

ExStruct also ships one repo-owned Skill for agents that should follow the editing CLI safely instead of rediscovering the workflow each time.

Canonical repo source:

• .agents/skills/exstruct-cli/

You can install it with the following single command:

npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli

If your runtime cannot use npx skills add, place the same folder manually into a local skill directory that discovers SKILL.md-based skills.

Use this Skill when the agent needs help choosing between patch, make, validate, ops list, and ops describe, or when it should follow the safe validate -> dry-run -> inspect -> apply -> verify workflow.

Example prompt for agents:

Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run/inspect workflow, and explain any backend constraints for this workbook task.

MCP Server (stdio)

MCP is the integration / compatibility layer around the same editing core. Use it when you need host-managed path restrictions, transport mapping, artifact mirroring, or approval-aware agent execution. For ordinary Python workbook editing, openpyxl / xlwings are usually a better fit. For local shell or agent workflows, prefer the editing CLI.

Quick Start with uvx (recommended)

You can run it directly without installation:

uvx --from 'exstruct[mcp]' exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename

Benefits:

• no pip install required
• automatic dependency management
• isolated environment
• easy version pinning: uvx --from 'exstruct[mcp]==0.4.4' exstruct-mcp

Traditional installation

You can also install it with pip:

pip install exstruct[mcp]
exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename

Available tools:

| Tool name | Description | | ------------------------------- | -------------------------------------- | | exstruct_extract | Extracts data from a workbook. | | exstruct_capture_sheet_images | Captures sheet images. | | exstruct_make | Creates a new workbook. | | exstruct_patch | Applies editing patches to a workbook. | | `exstruct_read_json_chunk