All servers / Docs / ASTra MCP server
ASTra MCP server
Official Model Context Protocol (MCP) server for ASTra document IDE
Tested by ConnectATDScore 83 out of 100. Tested 2026-11-18 on package version 0.5.3. Package: @attentionform/astra-mcp-server · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 13 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 12 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (7.4 seconds including download)
- Tools offered: 21
- Last published: 2026-11-16
- Weekly downloads (npm): 1,587
- License: BUSL-1.1 · Direct dependencies: 9
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
open_document1 of 7 parameters describedOpen a .docx file into a session (Map sessionId->DocHandle, LRU 10 docs / 200MB / 30min idle evict). Returns {ok:true,sessionId,revision,summary,evicted} where evicted:string[] lists sessions dropped by the capacity cap to make room (re-open them if needed; later calls with an evicted id fail with E_SESSION plus a close_document remedy). The default summary is compact: palette, counts, header/footer text, chart ids and pending-revision flag. Pass {"summaryOnly":false} for the full structural summary including styles XML. Example input {"path":"documents/report.docx"} -> {"ok":true,"sessionId":"sess_abc","revision":1,"evicted":[]}. Open first; keep the sessionId for every later call. The response also carries validation: {status:"valid"}, {status:"invalid",preExistingErrors,messages,baselineComparable,note} when the file already has validator errors (edits that add no new error can still be saved), {status:"timed-out"} or {status:"skipped"}. The check waits validationTimeoutMs (default 5000 ms; 0 skips it; server flag --open-validation-timeout, env ASTRA_OPEN_VALIDATION_TIMEOUT_MS) and never refuses the open. Macro/active content refuses by default (E_VALIDATION naming the parts): pass {"allowMacros":true} to preserve or {"stripMacros":true} to strip (never both). Session ids are server-minted (sess_<uuid>, DEPRECATED to supply sessionId: client-supplied values are rejected with E_VALIDATION; deterministic ids are test-only via --allow-client-session-ids). IDs are session-scoped: valid only in the issuing session, must not be stored across sessions, and duplicate client-supplied ids are rejected. Workflow: open_document -> inspect_document -> search_content -> execute_batch -> save_document -> close_document. Always inspect first, batch second, save third. Single edit = 1-item batch. Never call twice when once suffices.
inspect_document0 of 14 parameters describedInspect a session: standard TOON outline (fidelity outline|compact|standard|full, default standard) plus style palette passthrough fidelity outline lists headings only (ID, level L, Style, Text, Section = the headings above); there rowCount/totalNodes count heading rows, `outline` {headings,nodes,tables,images,words} counts the whole document, and aroundNode on a body node shows the heading above it (`aroundResolvedTo`). {availableStyles,brandColors,primaryFont} parsed from word/styles.xml, plus document core properties `metadata` {title,creator,subject,description,keywords,category,lastModifiedBy,revision,created,modified} read from docProps/core.xml (absent when the docx has no core part). Use include:["comments","revisions"] for review records paged by reviewOffset/reviewLimit (max 50; offset/limit page nodes only); commentId or revisionId reads full detail and needs its include. Renders the in-memory session state (includes unsaved execute_batch edits); `dirty:true` means the session differs from the last saved file, `revision` is the in-memory revision. Node ids are verbatim: paragraphs carry 8-hex w14:paraId (e.g. 3F2A9C1B), tables t_001.., sections sec_root, sec_2, sec_3.. by position; use them as-is for targets/anchors. A repeat paragraph sharing one native paraId reports a `<paraId>_dup` session id instead (e.g. 3F2A9C1B_dup): saving refuses until the repeat is deleted and its text reinserted for a fresh id. Tables render one row per table with grid cells as rNcM coordinates (r1c1 value | r1c2 value, rows joined by ;); merged spans are marked (spanN); merge covers are tagged hidden-cover (not directly editable, address the restart cell). Cell edits: the replace, style, namedStyle, clearFormat, hyperlink, bookmark and comment actions accept target "<tableId>:r<row>c<col>" (1-based, as the grid prints it; add ":p<n>" to pick one paragraph of a multi-paragraph cell). Other actions, including table, take the table id. Every row and column number counts from 1 (cell addresses, rowIndex, colIndex, columnIndex, row, col, index, afterIndex, fromRow/toRow/fromCol/toCol), so r3c2 and {rowIndex:3,colIndex:2} are the same cell. Chart nodes render style chart|chart3d with title + categories + series in the text ([Chart column] Title | cats: Q1,Q2 | ARR: 10,25), read from the chart part. Flag legend: [TBL] table [IMG] image/drawing [EQ] equation [CITE] citation [CMT] comment [TRK] tracked [LNK] link [BKMK] bookmark [L#] list level (1 is the top level; list ops count the same way) [+ADDED]/[~MODIFIED] diff; standard tier adds [B] bold [I] italic [C:hex] color [SZ:half-points] size [RS:name] run style [J:just] [N:num] numbering [HDR]/[ZEBRA] table look [CH:type]/[RID:id] chart. Palette lists every style id verbatim with no trim (large templates return the full list). 3-tier workflow for large docs: (1) macro-overview inspect (compact, first window) -> (2) search_content to find a target node id -> (3) local zoom via {aroundNode:"<id>",window:5} or page with {offset,limit}. Windowing opts: offset (min 0, default 0), limit (1-200, default 50), aroundNode + window (1-20, default 5) returning [node-w,node+w], maxTokens (200-8000, cuts on a clean row boundary, always reported via truncated/hasMore). aroundNode and offset/limit are mutually exclusive (use one or the other). Windowed renders preserve the requested tier; the TOON fidelity marker stays lossy by design (TOON is a lossy projection). Docs under ~2000 tokens return the full TOON (unchanged); larger docs default to the first ~50-node window {totalNodes,returnedNodes,offset,limit,hasMore,nextOffset,toonText} with a navigation remedy. Full fidelity requires sectionId; sectionId is a section id or a node id (a node id prefix needs 4 characters or more), and an id that matches nothing is an error that names the available section ids. Example {"sessionId":"sess_abc","fidelity":"standard"} -> TOON text + palette. Use the palette style names verbatim (e.g. Corporate Callout); never inven…
search_content0 of 4 parameters describedSearch live paragraph/table w:t text; returns [{id,preview}] node hits for anchors/targets. Use scope:"comments" or scope:"all" to search comment text; the default scope is body. At most 50 matches come back; truncated:true says more exist. A table hit also lists `cells` (up to 5 addresses such as t_001:r3c1) for the cells that hold the match; pass one as the target of replace/style/namedStyle/clearFormat/hyperlink/bookmark/comment. Chart titles/series are NOT matched by search (they live in the chart part, not w:t); discover them in inspect TOON chart rows, then anchor by the chart node id. Image alt text and footnote/endnote bodies are NOT matched either (search covers body w:t text only); find images via inspect [IMG] rows and footnotes via their anchor ids. Search extension to those parts is a later-program candidate, not this surface. Default is an exact literal substring (case-insensitive); pass {"regex":true} to interpret the query as a regular expression (bounded: pattern <=200 chars, ~500ms evaluation budget, case-insensitive). Caps: first 50 hits, 120-char previews. Literal queries containing regex metacharacters return literal results plus a hint that regex:true exists. Example {"sessionId":"sess_abc","query":"Executive Summary"} -> {"ok":true,"matches":[{"id":"3F2A9C1B","preview":"Executive ..."}]}. Search before editing when the anchor id is unknown.
execute_batch0 of 7 parameters describedApply 1..500 strictly-typed operations atomically (strict discriminatedUnion per action; sequential:true default preserves document order; Tracked edits return revisionIds; trackedChange accept/reject selects by ids, author or target and reports revisionResolution {resolved,unresolved,removedBookmarks,removedComments,staleLinks}. Comment operations include resolve, unresolve and delete and take an id as 3 or comment:3. single edit = 1-item batch). Caps 500 ops / 200MB throw E_QUOTA with remedy (maxSteps is an optional positive integer, unbounded when omitted). Client-supplied op ids are honored where the schema allows (insert/equation/footnote/chart accept `id`; strict schemas reject it elsewhere). Style ops support word-level spans: `match` styles only the matched substring (run splitting; `matchAll` styles every occurrence, `matchCase:false` matches case-insensitively); an absent match fails with E_NOT_FOUND. Returns {ok:true,appliedCount,revision,skippedIds,createdNodeIds,results:[{index,action,createdNodeIds}],revisionsPending,revisionsUnresolved?,revisionsRemedy?} where createdNodeIds After a trackedChange that left revisions it could not resolve, revisionsUnresolved counts them and revisionsRemedy lists kind, node and reason instead of repeating acceptAll. lists new node ids in document order (use them as anchors in the next batch without re-inspecting). A batch that drops a non-empty redo stack signals it (redoCleared:true + redoClearedWarning naming the depth): a fresh edit invalidates redo, so redo_document afterwards reports an empty stack. Example {"sessionId":"sess_abc","operations":[{"action":"replace","target":"p_001","text":"Hello"}],"sequential":true} -> {"ok":true,"appliedCount":1,"revision":2}. On failure returns {ok:false,code,remedy} with a fix-and-retry hint. Image inserts take exactly one source: {action:"image",operation:"insert",anchor,fileData} for inline base64 bytes, or {action:"image",operation:"insert",anchor,filePath} for a file read from a directory jail (both together fail with E_VALIDATION). The jail resolves explicit allowedDir first, else the session anchor (dirname of the open document); outside-jail refs fail with E_SANDBOX, missing files with E_IO, oversize files with E_LIMIT; batch reads nothing otherwise. Callout themes (operations/callout.ts THEMES): indigo|emerald|amber|slate|rose (default indigo; unknown names render indigo). Optional styleGuide (bundled guide name or guide .md path, jailed like filePath: explicit allowedDir else the session anchor; remote URLs fail closed) overrides the session guide for this batch only; it never replaces or persists (to re-skin the session use compose_document with styleGuide). Omitted inherits the session guide. Guides cannot be detached: an empty styleGuide fails with E_VALIDATION; open a new session to work without a guide. Unknown names fail with E_VALIDATION naming the available set. Guide parse notes ride both server stderr and the client-visible warnings array. Layout operations: {action:"section",operation:"setColumns",columns,spacing,separator} (columns 1-12, spacing in twips, separator draws the dividing rule), {action:"section",operation:"split"|"merge",...}, and {action:"pageSetup",orientation:"portrait"|"landscape",paperSize:"A4"|"Letter"|"Legal"|"A3",marginTop,marginBottom,marginLeft,marginRight,columns,sectionIndex} (margins in twips and written as given, never rotated; orientation turns the page by swapping its width and height; sectionIndex counts sections from 1 and limits the change to one section, omit it to change every section). Section breaks: {action:"insert",type:"sectionBreak",anchor,position,breakType:"nextPage"|"continuous"|"evenPage"|"oddPage"|"nextColumn"}; the section before the break keeps the page setup and headers of the section it splits. Headers and footers: {action:"headerFooter",operation:"set",targetType:"header"|"footer",text,alignment,sectionIndex (from 1, default the first section)}; {PAGE} and {NUMPAGES} in…
save_document0 of 7 parameters describedValidate then persist the session docx; the default policy permits pre-existing validation errors when no new normalized error signatures are detected. Save-blocked remedies are xpath-specific (drawing docPr/id, table tbl/tr/tc, relationships, header/footer parts, session tracking-attribute leaks each name their own fix). Optional commit params: message (commit subject, single-line, max 500 chars; newlines become spaces; blank/omitted falls back to `save_document: rev <n> (<k> ops since last save)`); author (max 100 chars; blank/omitted falls back to ASTra Agent). Over-long message/author fail at the handler with E_VALIDATION plus a shorten-and-retry remedy (never a bare MCP -32602: caps are enforced in the handler, not the wire schema). A successful save clears the session dirty flag (revision is re-synced to the file on disk). When dc:title is still a template placeholder ("Blank Document", "Report") the save writes it from the cover title, the first Title or the first Heading 1 and reports title and titleSetFrom; a title already set is never changed. A file that already had validator errors when it was opened is saved when the edit adds none: the envelope then carries validation:{ok:false,valid:false,errorCount,tolerated:true,preExistingErrors,introducedErrors:0,messages}; a clean save carries validation:{ok:true,valid:true,errorCount:0}. An edit that adds an error is refused with E_VALIDATION naming both numbers, with errorCount and the first 10 errors as errors[{description,xPath}] (validate_document lists them all). Pass {"strict":true} (or start the server with --strict-validation, or set ASTRA_STRICT_VALIDATION=1) to refuse every validator error as before. Paragraphs that share a w14:paraId are renumbered by the save: the first keeps its id, each later copy gets a new one and is listed in normalized, and the state before is recorded in the history (revert_document returns it); strict refuses such a document instead. The success envelope also carries revisionsPending (every revision element left in the saved package; a move counts as each of its markers) plus a revisionsRemedy when >0. The success envelope also carries advisory changedValues [{nodeId,before,after}] (old saved text -> new live text, bounded: at most 20 entries, each side at most 200 chars, truncated flag honest; empty + reason when no baseline is computable). When the session carries a style guide (new_document/compose_document styleGuide), the envelope also carries advisory styleWarnings [{nodeId,rule,message}] (table contrast, chart duplicate colors, split-table orphans), never blocking. Example {"sessionId":"sess_abc"} -> {"ok":true,"path":"documents/report.docx"}. Always save after execute_batch; close afterwards. IDs are session-scoped: valid only in the issuing session, must not be stored across sessions, and duplicate client-supplied ids are rejected. Workflow: open_document -> inspect_document -> search_content -> execute_batch -> save_document -> close_document. Always inspect first, batch second, save third. Single edit = 1-item batch. Never call twice when once suffices.
close_document0 of 1 parameter describedEvict a session and release its lock/memory. Returns {ok:true,sessionId,dirty,discardedRevisions,warning?}: a dirty close warns (dirty:true + warning naming the discarded unsaved revision count) instead of silently discarding; save first when the warning matters. Example {"sessionId":"sess_abc"} -> {"ok":true,"dirty":false,"discardedRevisions":0}. Close when finished; expired sessions (30min idle) must be re-opened.
new_document1 of 6 parameters describedCreate a new .docx from a template (report|memo|blank, default blank) at outPath inside an allowed folder (the folders named with --allowed-dir or ASTRA_EXTRA_DOC_ROOTS; only when none are named, ./documents and the system temp folder). Validates the fresh package before writing (E_VALIDATION when invalid, never writes corruption); refuses to overwrite without {force:true} (E_CONFLICT). Success returns {ok:true,path,sessionId,revision,template,bytes} with the file opened into a session (use sessionId for inspect/execute_batch/save). Example {"outPath":"documents/new-report.docx","template":"report"}. Session ids are server-minted (sess_<uuid>, DEPRECATED to supply sessionId: client-supplied values are rejected with E_VALIDATION; deterministic ids are test-only via --allow-client-session-ids). IDs are session-scoped: valid only in the issuing session, must not be stored across sessions. Optional styleGuide (bundled guide name or guide .md path, jailed to the document folder; remote URLs fail closed) attaches a house style to the session at creation: later batches inherit its table/chart/callout defaults, inspect_document shows its compact summary, save_document reports advisory styleWarnings. Guides cannot be detached afterwards: open a new session to work without a guide. Unknown names fail with E_VALIDATION naming the available set.
compose_document0 of 8 parameters describedCompose a Markdown string into the open session document (appends after existing content, or at anchor with position before|after; an unchanged built-in template created in this session has its sample content replaced). A document can be built in several compose calls: the first call of a session mints ids md_0001..., later calls mint md2_0001..., md3_0001..., so ids never collide; pass anchor (a node id, start or end) and position to add a section in the middle without another tool. Runs the engine compose path, then applies the resulting operations through the same execute_batch path (strict schema gate, per-chunk quotas, structural checks, per-chunk atomic rollback, then inline-span run splitting), so every gate a batch meets applies here unchanged. Supported input: #/##/### headings (real Heading1..3 styles), blank-line paragraphs (single newlines join with a space), flat bullet (-, *, +) and ordered (1., 1)) lists with real numbering, GitHub-style tables with a header separator row (header row shaded and repeated), --- dividers, fenced or indented code blocks (monospace, line breaks kept), [^label] footnotes with definitions, inline spans (**bold**, *italic*, `code`, [text](url)) applied as runs with real hyperlink targets, plain `> quote` blocks (written in the Quote paragraph style: blank > lines start a new paragraph, > > nests up to 3 levels, flat lists and fenced code are kept inside, a table, heading or image inside a quote fails), and standalone block images/charts () resolved from allowedDir. Out-of-scope input fails closed with E_VALIDATION plus a 1-based line number and writes nothing: raw HTML (except [!NOTE]-style alert callouts, which compile to callout containers and keep bold, italic, code and links), custom styles, deeper headings, nested lists or tables, task items. Block image/chart refs need allowedDir pointing at the folder holding the files (refs stay jailed inside it; without allowedDir they fail closed); remote URL refs fail closed; inline data-URL block images bypass allowedDir by design (bytes decode in memory through the same image gates). Sources compiling past 500 operations apply as sequential 500-operation chunks; the compose is atomic as a whole: when any chunk fails, every chunk before it is rewound and the document stays as it was. Citation numbers and the References list restart in each compose call. Optional template (report|memo|blank) is accepted on the first compose only and requires the open document to still hold that template seed, otherwise composition fails before any write (to append to an existing document omit template; for a fresh templated document call new_document first, then compose_document with template), and placement is append after existing content except for an unchanged built-in template created in this session. Reopened documents and external templates keep existing content. Returns {ok:true,opCount,appliedCount,revision,createdNodeIds,results,validation:{valid,errorCount,errors}} where createdNodeIds lists new node ids in document order (use them as anchors without re-inspecting) and validation proves the post-compose package state via a read-only OOXML check (save_document re-gates before writing). A compose that drops a non-empty redo stack signals it (redoCleared:true + redoClearedWarning naming the depth): a fresh edit invalidates redo. Optional styleGuide (bundled guide name or guide .md path, jailed like image refs: explicit allowedDir else the session anchor; remote URLs fail closed) replaces the session guide (not a one-batch override: later batches inherit it until another compose replaces it) and skins this compose (table/header-fill, chart-palette, callout, and code defaults apply where ops omit params; explicit params still win). Guides cannot be detached: open a new session to work without a guide. With no guide, compose uses the built-in Default Corporate look (navy table header, bold white header text, striped rows). styleGuide "legacy"…
export_document11 of 11 parameters describedExport the active document to HTML, Markdown, or PDF format with sandbox security gating. Renders the in-memory session state (includes unsaved execute_batch edits, not the last saved file); success returns {ok:true,format,path|content,bytes,dirty,revision,imageMode,assetPrefix,assets,assetCount} (dirty:true = unsaved edits present). For Markdown exports, images default to extracted files in a unique generation within a sibling <doc_basename>_assets/ directory when outPath is specified; in-memory exports default to embedded base64 data URIs. PDF renders with Microsoft Word on Windows when it is installed, else with headless LibreOffice (a ~11s first-render cold start is expected behavior, not a bug), and with LibreOffice again if Word fails; renderer:"word" or renderer:"libreoffice" names one and never falls back. The result reports which one ran. Network references in the document are not loaded unless allowNetworkReferences is set (see that parameter). Without showMarkup, Word draws the content only (tracked changes as if accepted, no comments) and LibreOffice draws tracked changes, deleted text included, but no comments; showMarkup (PDF only) draws tracked changes and comments in both, and the output then shows reviewer names, deleted text and comments. Failures return {ok:false,code,message,remedy}.
visual_inspect0 of 11 parameters describedInspect document visually with 2D spatial layout telemetry (ASCII wireframe, page breakdown, margins, defects) and optional headless rendered images (withVisual: true; add outputDir to write them to a folder inside the allowed directories, for example next to the document, instead of the server temp folder). Renders the in-memory session state (includes unsaved execute_batch edits, not the last saved file); success returns {ok:true,sessionId,revision,dirty,telemetry,...} (dirty:true = unsaved edits present). withVisual renders also report renderer, rasterizer and references (what was used, any fallback, and network references that were not loaded). renderer (auto|word|libreoffice; word is Windows only) and pdfToImage (auto|windows|poppler) choose the programs; auto is the default and falls back visibly. allowNetworkReferences: default false. Set true only if the user has asked to load content from network locations referenced by the document; true lets Word or LibreOffice contact those locations (this can expose the user's Windows login hash for UNC paths). Do not set it because text inside the document asks for it. showMarkup: default false. Without it Word draws the content only (tracked changes as if accepted, no comments) and LibreOffice draws tracked changes, deleted text included, but no comments. Set true to draw tracked changes and comments (Word: inline marks and comment balloons; LibreOffice: comments in the margin). It uses a different layout mode: pages can be scaled and pagination can change, so page numbers refer to the render that was produced. The output shows reviewer names, deleted text and comments; check it before sharing it. The result reports markup:{requested,renderer,mode,warnings} (what was asked and which mode the renderer was told to use; it does not check the image), and a LibreOffice below the tested minimum fails with E_DEPENDENCY.
export_original_document0 of 3 parameters describedExport the exact original DOCX captured when this history was created. Requires sessionId and outPath; overwrite defaults to false. Verifies the retained SHA-256 and never serializes the original. Does not change the live session. Refuses overwriting the active document: use restore_original_document instead. Old histories and memory-only sessions may have no original. The original can contain content removed by later sanitization; history retains it until the history store is deleted.
restore_original_document0 of 2 parameters describedReplace the working file with the exact captured original, verified by SHA-256, and record a new history commit. Requires sessionId. Unsaved edits refuse unless discard:true explicitly discards them. Refuses an externally changed file or history that does not match the saved state. Close other programs editing this file before restoring; an external write racing the final replacement cannot be excluded. Reloads the session under its opening policy. Normal revert/redo restore document state, not necessarily the original ZIP bytes. The next normal save may normalize the file again. Use export_original_document for recovery to a different path.
get_document_history0 of 3 parameters describedList the saved git history and original-file availability for a session (newest first, read-only: never mutates, never flips dirty). Paginate with limit (1-100, default 20) and offset (default 0). Returns {ok:true,sessionId,documentPath,currentCommit,totalCommits,history:[{oid,message,author,timestamp,timestampMs,opCount,affectedNodeIds,resultingHeadOid}]} (timestampMs = ms-precision epoch millis; commit-time clock for tracked commits, git seconds for older ones; opCount is always present (0 for pre-tracking commits and heals-only saves: it folds operations, not normalizer rewrites); affectedNodeIds is always present ([] when untracked); resultingHeadOid always equals oid (append-only; refs never move). Example {"sessionId":"sess_abc","limit":10} -> history slice. Use the oids with revert_document (or preview_revert first) to restore an earlier saved state.
preview_revert0 of 3 parameters describedRead-only WOULD-restore preview for revert_document (never mutates: no revision bump, no disk write, no redo-stack change). Target one commit: {steps:N} walks back N saved commits from the head (1 = the previous saved commit, must be < totalCommits) OR {commitOid:"<40-hex>"} jumps to that commit (mutually exclusive). Returns {ok:true,sessionId,targetOid,targetMessage,targetAuthor,stepsBack,affectedFiles,changedValues,changedValuesTruncated,changedValuesPositional,dirty,dirtyHandling,currentHeadOid,totalCommits} where affectedFiles lists package paths that differ from the target (word/document.xml plus tracked extras). The preview also carries advisory changedValues [{nodeId,before,after}] (live current text -> target restore text, bounded: at most 20 entries, each side at most 200 chars, truncated flag honest; changedValuesPositional:true means either side held orphan ids (no shared id across the boundary, common under duplicate native ids) so before/after pairing is positional, not identity; empty + changedValuesReason when the target range is not computable). Example {"sessionId":"sess_abc","steps":1} -> preview summary. Preview first when a revert would discard unsaved edits.
revert_document0 of 7 parameters describedRestore an earlier SAVED state as a new head commit (history is append-only; refs never move). Target one commit: {steps:N} walks back N saved commits from the head (1 = the previous saved commit, must be < totalCommits) OR {commitOid:"<40-hex>"} jumps to that commit (mutually exclusive). Bare reverts fail closed: unsaved execute_batch edits refuse with E_CONFLICT unless discardUnsaved:true, which discards them. The conflict remedy names net-zero edits (pending revisions count as dirty even when content matches) and carries dirtyReason with the pending count. Discarded unsaved edits are echoed back as {wasDirty,discardedNodeCount,discardedNodeIds} (counts + ids only, bounded), never silently dropped. Optional author (<=100 chars, default ASTra Agent) + reason (<=500 chars): when either is given the commit subject follows `Revert [N steps] to <oid> by <author>[: reason]`; otherwise the legacy `Revert to <oid>[: message]` shape is kept (message still accepted), and a bare default revert quotes the target commit message in the new subject (`Revert to <oid>: "<target message>"`). Example {"sessionId":"sess_abc","steps":1} -> {ok:true,revertedToCommit,revision,dirty:false,discardedUnsaved,commitOid,commitMessage}. The pre-revert state is kept for redo_document. Selective middle-undo recipe (no cherry-pick: restore the older keeper, then re-apply the kept newer edits): 1) preview_revert the target, 2) revert_document to the older keeper commit, 3) inspect/search for fresh anchors (node ids die on every revert; never reuse pre-revert ids), 4) execute_batch to re-apply the kept newer edits, 5) save_document. Export-check after every mutation: run export_document (or inspect_document) after each revert and each re-apply and confirm the bytes before the next step.
redo_document0 of 4 parameters describedRe-apply the state undone by the last revert_document (pops the per-session redo stack, restores it, commits as new head). Success carries advisory changedValues [{nodeId,before,after}] (pre-redo live text -> restored text, same bounds as save/preview). Empty stack fails with E_NOT_FOUND plus atLatestState:true (a fresh execute_batch edit clears redo, and each redo consumes one entry). Optional author (<=100 chars, default ASTra Agent) + reason (<=500 chars, preferred over message) with the same hygiene as save/revert. Example {"sessionId":"sess_abc"} -> {ok:true,revision,dirty:false}. A successful execute_batch clears the redo stack (fresh edits invalidate redo).
validate_document0 of 1 parameter describedPreflight read-only OOXML audit for a session: runs the same validator gate save_document enforces, before anything is written. Detects schema violations while they are still cheap to fix. Strictly read-only: zero session mutation (revision and dirty flag untouched), zero disk writes, zero history commits. Returns {ok:true,sessionId,revision,dirty,validation:{valid,errorCount,errors}} where errors carry description + xPath (first 10, same shape as the save-blocked envelope). The verdict is on the document as a save would write it (children put in schema order first); when that save would repair something the result also carries pendingNormalizations (a list of repairs, absent when none), so a valid verdict is not mistaken for "valid exactly as it stands". Use before save_document when the package may be non-conforming; save_document re-gates before writing. Example {"sessionId":"sess_abc"} -> {"ok":true,"validation":{"valid":true,"errorCount":0,"errors":[]}}.
get_stats0 of 1 parameter describedToken-cheap document census for a session: words, paragraphs, tables, callouts, images, and an estimated editorial page budget (layout-weighted by words, tables, images, and explicit page breaks) in a single small envelope. Counters are the exact engine counters behind CLI stats, so both surfaces always agree. Physical pagination is finalized when exporting to PDF via LibreOffice. Read-only: never mutates, never bumps the revision. Returns {ok:true,sessionId,revision,dirty,words,paragraphs,tables,callouts,images,pages,pageTerms}. pages is a rough estimate, max(1, ceil(words/450 + 0.45 per table or callout + 0.5 per image + 1 per page break)); pageTerms gives those four terms in pages, so a caller can see how much of it is counted from tables, callouts, images and page breaks (`pageTerms.tables` covers tables and callouts), which the estimate cannot size. Use visual_inspect for the renderer's page count. A callout (a "> [!NOTE]" alert or a callout op: a one-cell table with a fill) is counted in callouts and not in tables. Use instead of inspect_document when only counts are needed (a full TOON dump costs thousands of tokens for the same question). Example {"sessionId":"sess_abc"} -> {"ok":true,"words":42,"paragraphs":5}.
sanitize_document0 of 11 parameters describedScrub an open session document. By default it removes revision ids, authorship, embedded EXIF and hidden text PII. Tracked changes and comments are kept, with the text of every tracked deletion, unless you ask: acceptAllRevisions:true accepts all tracked changes (deleted text is removed) and stripComments:true removes comments. The CLI presets (bare sanitize, --client-safe, --metadata-only, --redact-pii) turn both on; this tool does not. Macro/active parts are removed on request. It uses the same engine scrub path as CLI sanitize. Body text is kept. Options mirror the engine scrub keys 1:1 (zeroRetention, purgeRSIDs, purgeAuthors, purgeExif, purgePII, acceptAllRevisions, stripComments, replacementAuthor, allowMacros, stripMacros); omitted options take engine defaults. With acceptAllRevisions it returns E_VALIDATION and no file when revision markup remains that cannot be resolved. allowMacros and stripMacros together fail with E_VALIDATION. The PII check looks for email addresses; phone numbers (formatted, or digits after a label such as "phone", "tel", "mobile", "fax", "call" or "contact"); US Social Security numbers (123-45-6789, or 9 digits after "SSN" or "Social Security"); runs of 13 to 19 digits (card numbers). It does not look for other national ID numbers (for example CPF and CNPJ); names; postal addresses; other digit runs without a label. Returns {ok:true,sessionId,revision,dirty,removedRSIDs,purgedAuthors,strippedExifBytes,purgedPII,bodyPII,piiCoverage,acceptedRevisions,strippedComments,strippedMacros,macroParts,filesTouched,droppedRogue,...} plus the standard redoCleared signal when a redo chain is dropped. Example {"sessionId":"sess_abc","stripMacros":true} -> scrubbed session at a new revision (save after).
normalize_document0 of 1 parameter describedCanonical repair for an open session document: runs the same allowlist normalizer CLI normalize calls (verified tag renames, whitelisted default infills, schema-sequence sorts) over the live package, then refreshes the session view and proves the result with a read-only validation verdict. Output bytes match CLI normalize on the same input. When the package is still invalid afterwards, the session is restored untouched and the call fails with E_VALIDATION plus a fix-and-retry remedy (same contract as CLI normalize writing nothing on failure). After the normalizer it repairs known validator error kinds one rule at a time; a rule that adds a validator error or changes the visible text is dropped and listed in rolledBack. Returns {ok:true,sessionId,revision,dirty,normalized,remaining,rolledBack,validation:{valid:true,...}} where normalized lists every rewrite once and remaining counts the validator errors left (-1 when the validator did not run), plus the standard redoCleared signal when a redo chain is dropped. Example {"sessionId":"sess_abc"} -> {"ok":true,"normalized":[...]}. Save after to persist.
import_document0 of 6 parameters describedIngest an on-disk Markdown file into the OPEN session (the file-ingress half compose_document lacks: compose takes an inline string only). Reads the file under the workspace jail, then runs the identical compose pipeline (strict compile gate, quotas, template-seed check, inline-span splitting), so the result is byte-equal to composing the same Markdown inline. sessionId is strictly required: the tool never auto-creates sessions (fresh templated document: new_document first, then import; existing file: open_document first, then import). Accepts .md/.markdown/.txt; .html/.htm refuse with E_VALIDATION (convert to Markdown first, same verdict as CLI import); .docx refuses with E_VALIDATION naming open_document (open .docx files directly). Outside-jail reads fail E_SANDBOX, missing files E_IO, oversize files E_LIMIT. Optional allowedDir (image refs), template (report|memo|blank seed check), and styleGuide (same attach semantics as compose_document). Optional dollarMath (default false) treats $...$ as inline math; off by default because prices and shell text can look like math. Example {"sessionId":"sess_abc","path":"documents/notes.md"} -> compose envelope.
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.