io.github.Anselmoo/mcp-ooxml-ledger

Apply a batch of edits to the document and record each one in the session's journal. ALL-OR-NOTHING: the document is written only if every edit applied, so a failed batch leaves the file byte-identical and journals nothing. `mode` 'tracked' emits Word revision marks a reviewer can see; 'direct' rewrites the text and is recorded in the ledger alone, which the receipt discloses. Seal the session with `commit_document`.

End a session and delete its working directory WITHOUT sealing a receipt. Refuses when the journal holds recorded operations unless `discard` is set — closing over them would throw away the accountability record.

End a session by sealing its journal into a receipt, but only if the recorded operations account for every change to the document. If they do not, the commit is REFUSED. `force` overrides a failed gate VERDICT and the override is recorded in the receipt, where `verify` will surface it; it does not override a ledger that could not be read or replayed at all.

Delete one whole paragraph and record it in the session's journal. Address it by `para_id` — the `w14:paraId` `find_text` returns — or by `para_index` TOGETHER WITH `para_hash`, because an index alone silently addresses a different paragraph once anything above it moves. `mode` 'tracked' marks the paragraph mark AND every run with `w:del`, so a reviewer can reject it back and nothing is actually removed; 'direct' removes it outright and is accounted for by the ledger alone, which the receipt discloses. Refused if the paragraph carries a section break, or holds an unaccepted revision by another author. Seal the session with `commit_document`.

Report a session document's structure: which parts the digest covers, which it excludes, and the format's own units — paragraphs for docx, sheets for xlsx, slides (in <p:sldIdLst> order, never filesystem order) for pptx. Describes the session's working copy as opened; `verify` reports on the file on disk now.

Compute a document's canonical digest — stable across a no-op Office save, and the key a receipt is stored under. Needs no session.

Write this document's receipt out as one self-contained sidecar file — the thing you attach to a submission, commit to git, or register alongside a DOI.

Case-insensitive substring search over every text-bearing part the digest covers, returning the best address this build can give for each hit: paragraph id or index and hash for docx, slide id for pptx, sheet and cell for xlsx. On pptx, real slides (in presentation order) are visited before slide layouts, masters and notes masters, so the default page surfaces slide content first. Each match's `text` is a bounded window around the hit, not the whole run — `text_length` and `match_offset` locate it in the full run, and `text_truncated` says whether it was cut; a large result set can also stop early on total response size, reported the same way as `max_results` paging: `truncated=True`. Results come from the session's working copy as opened; `verify` is what reports on the file currently on disk.

Insert a new paragraph carrying `text`, BESIDE a paragraph you name, and record it in the session's journal. Pass exactly one anchor — `after_para_id` or `before_para_id`, the `w14:paraId` `find_text` returns. `para_hash` is OPTIONAL and recommended: the paraId already names one specific paragraph, and passing the hash `find_text` reported with it additionally refuses the call if that paragraph's text has moved on since you read it. There is deliberately NO raw index parameter. The new paragraph becomes a SIBLING of the anchor, which keeps it inside the same table cell, textbox or content control. `mode` 'tracked' marks the new paragraph and its run with `w:ins`, so rejecting removes the whole paragraph; 'direct' writes it unmarked and is accounted for by the ledger alone, which the receipt discloses. Seal the session with `commit_document`.

List every receipt in the store beside a document, flagging the one whose result digest matches the document as it stands now, and naming every file that was skipped and why.

Start an editing session: unpack the document to disk, record its baseline digest and part manifest, and sweep expired sessions. Reopening the same unchanged document resumes its live session instead of forking a second one.

Report what a batch of edits WOULD do, writing nothing. Runs the same engine against a throwaway copy of the document as it stands on disk right now — including every edit already applied in this session — so a green preview and the apply that follows it cannot disagree. `author` and `mode` are required because the engine's refusals depend on both.

Versions, allowed roots, and what this build can and cannot do.

Check a document against its receipt. Reports three distinct outcomes: verified, unknown (no receipt matches this digest) and failed (a receipt matched but a tier failed). Needs no session — the same check runs in CI via `ooxml-ledger verify`.