One tool, three formats

office_read takes a Word, PowerPoint, or Excel file and returns clean markdown (plus the plain text). The format is auto-detected from the file contents — they are all ZIP containers, told apart by what's inside — so the agent never has to pick; it just says "read this file."

It pairs with the hub's other readers: hirarapdf for PDFs and hiraraocr for images and scans. This one owns the Office formats.

Legacy binary formats (.doc / .xls / .ppt) are recognized and rejected with a clear message — save as the modern OOXML format instead.

Quick start

pip install -e ../hirara-core        # shared SSRF guard (repo-local)
pip install -e ".[service,mcp]"

As an HTTP service:

uvicorn hirarareader.service:app --host 127.0.0.1 --port 8500

Read a document (base64, path, or URL) → markdown + text:

curl -X POST localhost:8500/office_read -H 'content-type: application/json' \
  -d '{"file_path":"/path/to/report.docx"}'

Or upload it directly:

curl -X POST localhost:8500/office_read/upload -F file=@deck.pptx

As an MCP server over stdio (Claude Desktop / Cursor / agent runtimes):

python -m hirarareader.mcp_server

With Docker (loopback-bound, nothing to download at boot):

docker compose up -d --build

API

Response carries kind (docx/pptx/xlsx), markdown, text, meta (paragraph/slide/sheet counts), truncated, source, and error. Errors come back in the body, not as HTTP status codes: the caller is an agent loop, and "unrecognized document" is a result to reason about.

Security

• file_url is off by default. When enabled (CRDR_ALLOW_URL_FETCH=true), the fetch goes through hirara-core's safe_download — resolve-then-pin, every redirect hop re-validated, streamed under a byte cap — never a bare httpx.get.
• Local file access is gated. file_path lets a caller name any file on the host; fine for a local/MCP server, off in the Docker image. Set CRDR_ALLOW_LOCAL_PATH=true only for a trusted, local deployment.
• Everything is size-capped — input by CRDR_MAX_BYTES, output by CRDR_MAX_CHARS (flags truncated), spreadsheet rows by CRDR_MAX_ROWS.

Configuration

All via environment variable.

Testing

pip install -e ".[dev]"
pytest -q

The suite builds tiny real .docx/.pptx/.xlsx files in memory and reads them back — so it exercises the actual libraries end-to-end, no fixtures checked in. Verified on a live server: all three formats read to the expected markdown.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 Lucas D Marshall (Kaung Myat San).