documents.js MCP sunucusu

documents.js

A family of independent, MIT-licensed TypeScript packages for lossless, type-safe document conversion — OOXML (docx/pptx/xlsx), OpenDocument (odt/ods/odp), Markdown, EPUB, and PDF — sharing a common Zod-based schema layer, plus the CLI, MCP server, and web UI built on top of them.

This repository is a pnpm workspace: one repository, one lockfile, one CI pipeline, and one release run, holding every package in the family under packages/. Each package keeps its own version, its own changelog, its own npm release cadence, and its own README — consolidating the repositories did not merge the packages into one artifact, and there is no lockstep version shared between them. What is shared is everything that was previously copied: the workspace settings, the task pipeline, the git hooks, commit-message validation, dependency automation, and the release orchestration.

Getting started

Node 24 (pinned in .tool-versions) and pnpm (the version pinned as packageManager in the root package.json) are the only prerequisites; corepack resolves the latter automatically. pnpm install resolves and links every package in one pass — there is no per-package install step.

No environment variable is required for a normal build/lint/test run. documents.js's examples suite regenerates its fixtures only when GENERATE_EXAMPLES is set; pnpm test:corpus additionally expects the gitignored real-world conformance corpora to already be present locally (see each codec's own README for what it checks against).

Packages

The packages layer from foundation up to user-facing interfaces. Each depends only on the layers below it.

Foundation

Package	What it is
document-schema.js	The canonical, format-agnostic content and document-tree schema shared by every codec, plus the structural transform between them (decompose/flattenTree/factorStyles/assembleTree, converting a flat ContentDocument to and from the tree-form DocumentTree). Free of any format-specific or I/O behaviour: the transform lives here because every codec depends on this package and none of them depends on documents.js, so it is the only layer a codec can reach to expose DocumentTree publicly without a dependency cycle.
byte-codec	Generic byte-level primitives (ByteWriter, ByteReader, CRC-32, deflate/inflate, base64) and PNG/JPEG image encoding and decoding, with zero knowledge of any document format. The base64 pair is the one every codec shares for an image payload or a data: URI, so no codec carries its own.
document-outline.js	Utilities for consumers holding a tree-form DocumentTree: the TOC outline projection, effective-property resolution, and the flatten/leaf-text/stable-hash helpers. Depends on the schema alone, and is consumed by the interface packages rather than by the codecs.
archive-codec	Recursive archive (ZIP-in-ZIP) detection and walking with depth and cumulative decompressed-size guards, plus bounded classic OLE compound-file ([MS-CFB]) reading, conformant [MS-CFB] writing, and OLE Package stream reading and writing — zero document-format knowledge. Consumed by ooxml.js, whose pptx (p:oleObj) and docx (o:OLEObject) OLE reading detects a ZIP-payload embedded object through it and decodes the nested package as a content document, and unwraps the classic .bin compound-file spelling through its CFB reader to the same nested decode; the writer is the container the legacy binary codecs need before any of them can gain a write path, and rtf-codec builds its own Package-stream-wrapped embedded objects through the identical pair.
document-compute.js	Units-typed evaluation over the schema's MathExpression: evaluate() for point values and bounded intervals through one interpreter with exact-rational unit conversion, plus solveFor() numeric root-finding on one unknown. Depends on the schema alone; consumed by document-mcp's compute_formula tool, not by any codec or the conversion engine.
excel-number-format	A tokenizing classifier for Excel's number-format mini-language (ECMA-376 Part 1 §18.8.30, which BIFF8's [MS-XLS] 2.4.126 defers to): deciding whether a numeric cell's format code says percentage, currency, date, time, elapsed duration, or plain number. No document-format knowledge of its own; shared by ooxml.js's xlsx support and xls-codec's BIFF8 reading, since the two formats inherit the identical mini-language.

Format codecs

Each converts one document format to and from the shared schema, built on document-schema.js:

Package	Formats
ooxml.js	OOXML packages (docx, pptx, xlsx) to and from JSON.
odf.js	OpenDocument packages (odt, ods, odp, odg) to and from JSON, plus read and write support for the pre-OASIS OpenOffice.org 1.x documents ODF was based on (sxw, sxc, sxi, sxd).
markdown-codec	CommonMark+GFM to and from the shared content schema.
pdf-codec	Parses arbitrary real-world PDFs and generates new ones, also depending on byte-codec.
epub-codec	Flowable EPUB 2/3 to and from the shared content schema; writes EPUB 3 only.
rtf-codec	Rich Text Format to and from the shared content schema; hand-written tokenizer, destination state machine, and header-table parsers, since RTF is tokenised text rather than XML, also depending on archive-codec for the [MS-CFB] container an embedded object's \objdata carries.
wpd-codec	WordPerfect 6.x-X6 (.wpd) to the shared content schema; read-only, and under active development.
doc-codec	The pre-2007 Word Binary File Format (.doc, [MS-DOC]) to and from the shared content schema, also depending on archive-codec for its [MS-CFB] container; write support covers character/paragraph formatting (including numbered/bulleted lists and named styles), multiple sections, tables, cell decoration, PNG/JPEG inline images, page breaks, footnote/endnote/comment bodies and header/footer stories, and metadata, with style-inherited formatting, note references, embedded objects, and construct-boundary markers still gaps — see the package's own README for its exact scope.
xls-codec	Legacy Excel Binary File Format (.xls, BIFF8) to and from the shared content schema, also depending on archive-codec for its [MS-CFB] container; write support covers cell values, merges, row/column sizing, number formats, cell background/border decoration, cell alignment, print settings, same-sheet formulas, and images/embedded objects (charts excepted), with per-cell fonts and defined names the remaining permanent gaps — see the package's own README for its exact scope.
ppt-codec	PowerPoint 97-2003 binary presentations (.ppt, [MS-PPT]) to and from the shared content schema, also depending on archive-codec for its [MS-CFB] container and byte-codec for OLE-storage decompression; the write side covers text-box, picture, and table shapes with rotation and per-shape text insets, OLE-embedded objects are detected and linked both ways through an injected serialise/decode port pair (this single-format package depends on no sibling codec to turn an embedded object's own nested content into bytes or back), and both directions remain under active development.

Rendering backends

Package

What it is

pdf-raster-cpu

The pure-software reference implementation of pdf-codec's PageRasteriser port: renders a PDF page, or one located region of one, to PNG bytes with a scanline rasteriser that has no canvas dependency, so it runs identically under Node, a browser Worker, and workerd. pdf-codec defines the port and deliberately picks no implementation, so a runtime with a real canvas can supply its own backend instead.

Conversion engine

Package	What it is
documents.js	Bidirectional docx/pptx to and from PDF conversion, and a read+write editable OOXML document model, built on ooxml.js and depending on every write-capable codec above, including doc-codec/xls-codec/ppt-codec, plus wpd-codec as a read-only conversion source (routable everywhere but never a target, since wpd-codec ships no writer).

Operations

Package

What it is

document-operations

The canonical set of document-conversion, editing, inspection, and .odb operations documents.js exposes — one Zod input/output schema and one transport-agnostic run() function per operation, built on documents.js, document-outline.js, document-compute.js, and document-schema.js. document-mcp and document-rest each register every operation as a tool/route rather than defining their own copy; document-cli's own flag parsing is meant to consume the identical registry too.

Interfaces

Each exposes the conversion engine through a different surface:

Package	Surface
document-cli	CLI and interactive Ink TUI covering every docx/pptx/odt/odp/ods/odg/odf/pdf/odm/odb/xlsx/markdown conversion, bridge, and editor as a scriptable command or a terminal app.
document-mcp	MCP server exposing the conversion, .odb, metadata, font, and paragraph-editing tooling as MCP tools, dispatching to document-operations for the actual implementation of each one.
document-rest	A plain REST API server exposing every document-operations operation as a JSON-over-HTTP POST route, for a caller with no MCP client and no Node runtime of its own.
web	Client-only, statically-built web UI for every conversion and editing tool in the ecosystem, also depending directly on markdown-codec. The one package here that is never published: it deploys to GitHub Pages instead.