Mcp Ooxml Ledger

mcp-ooxml-ledger

[CI] [codecov] [PyPI] [TestPyPI] [Python] [License: MIT] [MCP]

An MCP server that edits Office documents and refuses to write one where an edit went unrecorded.

Before sealing a session it replays every recorded operation against the document's baseline and compares the result to what is actually on disk. A change no operation explains means the commit is refused. Of ~18 competing MCP document-editing projects, none gates the write on that check. The refusal is the product.

Setup

uv add mcp-ooxml-ledger

Add to .mcp.json (project) or claude_desktop_config.json (desktop — use an absolute path, ${CLAUDE_PROJECT_DIR} isn't expanded there):

{  "mcpServers": {    "ooxml-ledger": {      "command": "uv",      "args": ["run", "--project", "${CLAUDE_PROJECT_DIR}", "ooxml-ledger-mcp"],      "env": { "OOXML_LEDGER_ROOTS": "${CLAUDE_PROJECT_DIR}" }    }  }}

Needs uv on PATH; nothing else installed globally. Invoking the ooxml-ledger-mcp script directly gives ENOENT — it lives in the project venv, not your shell's PATH.

OOXML_LEDGER_ROOTS is the security boundary. An os.pathsep-separated list; every path any tool receives is resolved inside it and refused outside. Unset, it defaults to the server's working directory — set it deliberately, since export_receipt writes anywhere inside a root.

Tools

Typical loop:

open_document → find_text → preview_edits → apply_edits → commit_document → verify

sid = open_document(document="report.docx")["session_id"]find_text(sid, query="Q3 revenue")                     # → part, para_id, para_hashpreview_edits(sid, edits=[...], author="alice")        # → what WOULD happen; writes nothingapply_edits(sid, edits=[...], author="alice", mode="tracked")commit_document(sid)                                   # → refuses if anything is unaccounted forverify("report.docx")                                  # → verified | unknown | failed

preview_edits runs the same engine function as apply_edits against a throwaway copy, so the two cannot disagree. Batches are all-or-nothing: a failing edit leaves the document byte-identical.

mode="tracked" emits Word revision marks a reviewer sees in the document. mode="direct" rewrites the text with none — still fully recorded, and the receipt discloses that a direct edit touched a revision-capable part, so it is never silently indistinguishable from an ordinary save.

Chat and hosted clients

A file uploaded into a chat lives in the client's sandbox, not on the server's filesystem, so open_document correctly refuses its path. Widening OOXML_LEDGER_ROOTS cannot reach it. Send the bytes instead:

import_document → open_document → … → commit_document → export_document

p = import_document(name="report.docx", content_base64="UEsDB…")["path"]  # → <root>/_inbox/report.docxsid = open_document(document=p)["session_id"]...                                                    # edit as usualcommit_document(sid)                                   # → receipt schema ooxml-ledger/2export_document(document=p)                            # → file + receipt as embedded resources

• Where it lands. import_document takes a bare filename and writes _inbox/<name> under the first root. It never overwrites an existing file, and it validates the bytes as a real Office package before anything is published.
• Large files. A model has to emit the base64 itself, so a single call carries far less than the cap. Send chunks: final=false returns an upload_id; continue with it and offset (the bytes received so far); the final=true call must carry the sha256 of the whole file. A lost or repeated chunk is a refusal, never a different document.
• Size cap. OOXML_LEDGER_IMPORT_MAX_BYTES sets the largest document either tool accepts, in decoded bytes. The default is 25 MiB.
• Provenance. An imported document's first bytes on this host came from a tool call, not from the user's filesystem. Every receipt in that lineage is therefore sealed as ooxml-ledger/2, with a chain-bound provenance block (docs/superpowers/specs/receipt-format-v2.md). verify prints it as a PROVENANCE line, and it never changes the verdict. Receipts for every other document stay ooxml-ledger/1, byte-identical to before.
• Getting it back. export_document returns the file as an MCP embedded resource, with its Office media type and the receipt alongside. By default it refuses a document that no stored receipt matches, so an unsealed edit is never handed out; pass require_receipt=false to override.

Format matrix

Verification, digests, the gate and the receipt model are format-agnostic. Only the editing engines are format-specific: wml.py (Word) and pml.py (PowerPoint).

Read-only deployment

OOXML_LEDGER_READ_ONLY=1 leaves exactly server_info, digest, verify, list_receipts, export_document. The others aren't merely hidden — calling one answers Unknown tool. No write surface inside the roots at all.

CLI

ooxml-ledger verify report.docx    # exit 0 only when verified

No server, no session — digests the file, finds its receipt by content address, checks it. Wire it into CI or a pre-commit hook and an unaccounted-for change fails the build.

Desktop bundle (.mcpb)

Every GitHub Release attaches a .mcpb file — a one-click Claude Desktop install: drag it onto the app and Desktop launches it with uv run --directory <bundle> --frozen --no-dev ooxml-ledger-mcp. Nothing is vendored — the bundle carries only manifest.json, pyproject.toml, uv.lock, README.md, LICENSE and src/. The host needs uv on PATH, and the first launch resolves the exact dependency versions uv.lock pins from PyPI, which needs network access; --frozen means it installs precisely the versions the test suite ran against, never a fresh resolve, and --no-dev keeps the dev group (pytest, ruff, pre-commit) out of the install. mcpb/manifest.json exposes the document root and read-only toggle as install-time settings instead of environment variables; the tool list matches the stdio server's.

CI builds and smoke-tests the bundle on macos-latest only, and the manifest's compatibility.platforms declares darwin only — the bundle is built and proven on macOS/arm64, nothing else. Because nothing is vendored, uv itself picks a Python satisfying requires-python = ">=3.13" and installs the wheels uv.lock pins for the host's own platform — native ones such as pydantic-core and cryptography included. That part is not darwin-specific, but only the darwin launch path has actually been proven end-to-end here.

Honest limits

• An unsigned receipt is accident-evident, not tamper-evident. It catches an agent falling back to a generic file write, an Office round-trip, a careless collaborator — not someone who rewrites the receipt alongside the document. Anchoring its hash somewhere the holder doesn't control (a git commit, a DOI, a submission portal) is what buys tamper-evidence.
• Imported provenance lives beside _inbox/. The import record sits in the store next to the imported file. Moving that file out of _inbox/ before its first commit drops the record, so the first receipt is written as v1. After a commit, the lineage travels with the receipts store. Provenance records what arrived, not that it matches the user's original upload: compare its sha256 out of band if that matters.
• A v0.3.0 verifier rejects ooxml-ledger/2. This is by design. It cannot check the genesis rule, so refusing is better than silently accepting a chain it does not understand.
• verify never replays. It checks the digest and the receipt's internal consistency; the replay runs once, at commit, and verify reports that verdict rather than recomputing it.
• pptx and xlsx have no human-visible record. Word tracked changes are a second recording layer inside the document; those two formats have none, so the ledger is the only record.
• The Word engine reaches paragraph text only (w:p/w:r/w:t). Styles, numbering, settings and relationships are uneditable and covered by the accountability check alone.

Contributing and security

CONTRIBUTING.md covers setup, the branch and commit naming CI enforces, and the release flow. SECURITY.md covers private vulnerability reporting, and is explicit about which of this project's documented limits are design rather than defects.

MIT licensed. Design notes and specifications live in docs/superpowers/.