Content
# animus-document-engine
An **MCP (stdio) service** that renders, parses, converts, and edits Office
documents — **Excel (.xlsx), PowerPoint (.pptx), Word (.docx)** — from a
structured JSON **spec**. It is identity-free and stateless: it never touches
subjects, S3, or users. The [animus-launchapp](https://github.com/launchapp-dev/animus-launchapp)
portal orchestrates it (storage + scoping + subjects); this engine is the reusable
rendering core.
Part of **REQUIREMENT-053** — Documents as subjects.
## Why a spec
The **spec is the source of truth**. An AI authors a spec (not raw OOXML); a
deterministic renderer turns it into a real file. Editing = mutate the spec and
re-render — lossless, reviewable, and diffable. Binary payloads cross the MCP
boundary as base64.
## Tools
| Tool | In | Out |
|------|-----|-----|
| `render_document` | `format`, `spec` | base64 OOXML bytes |
| `parse_document` | `format`, `bytes_base64` | spec (**xlsx only** in v1) |
| `apply_edits` | `format`, `spec`, `ops[]` | edited, re-validated spec |
| `convert_document` | `bytes_base64`, `to` | base64 converted bytes (e.g. `pdf`) |
| `preview_document` | `bytes_base64`, `kind` (`pdf`\|`png`), `page` | base64 PDF or PNG thumbnail |
`convert_document` / `preview_document` use **LibreOffice compiled to WebAssembly**
(`@matbee/libreoffice-converter`) — no native `soffice` needed. The ~112 MB WASM
lives in this service, never in the portal image.
## Spec shapes (v1)
```jsonc
// xlsx
{ "sheets": [ { "name": "Revenue",
"columns": [ { "header": "Month" }, { "header": "USD" } ],
"rows": [ ["Jul", 1200], ["Aug", 1500] ] } ] }
// pptx
{ "title": "Kickoff",
"slides": [ { "title": "Agenda", "bullets": ["Scope", "Timeline"] },
{ "title": "Next", "body": "…", "notes": "speaker note" } ] }
// docx
{ "title": "Spec",
"blocks": [ { "type": "heading", "level": 1, "text": "Overview" },
{ "type": "paragraph", "text": "…" },
{ "type": "bullets", "items": ["a", "b"] },
{ "type": "table", "rows": [["a","b"],["c","d"]] } ] }
```
`apply_edits` ops: `{op:"set",path,value}`, `{op:"append",target,value}`,
`{op:"remove",target,index}`, `{op:"replace",value}` (`target` = `sheets`\|`slides`\|`blocks`).
## Run
```bash
npm install
npm run build
node dist/index.js # MCP stdio server
```
Wire it into an Animus workflow phase (or any MCP client) as a stdio server:
```jsonc
{ "mcpServers": { "document-engine": { "command": "node", "args": ["dist/index.js"] } } }
```
## Dev
```bash
npm run dev # tsx watch (stdio server)
npm run typecheck # tsc --noEmit
npm run smoke # render all 3 formats + xlsx parse/edit round-trip
tsx scripts/mcp-smoke.ts # spawn the built server, call tools over MCP
```
## Scope (v1) & roadmap
- **Generate** all three formats — solid (pptxgenjs / docx / exceljs).
- **Parse** — xlsx (data + headers). **pptx/docx in-place parsing is DEFERRED** to
a future Python worker (python-pptx / python-docx are the only libraries that
faithfully round-trip arbitrary decks/docs); the engine errors loudly rather than
silently dropping content.
- **Convert/preview** — via LibreOffice-WASM.
