How it works

Why an agent can trust it with your document.

Six things happen between "change this" and a saved file. Each one is a guarantee, and each one below is shown with what the server really answered.

01 Read
02 Edit
03 Save
04 Undo
05 Contain
06 See

01 · Read

Your agent reads rows, not XML.

A Word file is a bundle of XML parts. Handing that to a model wastes its attention. inspect_document returns the document as compact rows: a stable node ID, the style, and the text. The agent can see structure at a glance and address any paragraph, table or chart by its ID.

Need to find something first? search_content returns the IDs of the nodes that contain it.

inspect_document

ID | V | Path | Header | Style | Text | Flags
--- | --- | --- | --- | --- | --- | ---
41E5F245 | 1 | Root |  | Heading1 | Atlas Robotics: Q3 2026 Board Report | 
6E34034E | 1 | Root |  | Heading2 | 1. Executive summary | 
2A8D004A | 1 | Root |  | body:L-1 | Revenue reached $14.2M in Q3, up 34.2% year over year, led by platf…
t_001 | 1 | Root |  | table:1x1 | r1c1 The board is asked to approve the $2.5M warehouse-vision expansi…
550B88F0 | 1 | Root |  | Heading2 | 2. Financial performance | 
t_002 | 1 | Root |  | table:6x4 | r1c1 Metric | r1c2 Q3 2025 | r1c3 Q3 2026 | r1c4 Change ; r2c1 Revenu…

02 · Edit

A batch is all or nothing.

Edits are typed operations, up to 500 in one execute_batch call. If any one of them fails, the whole batch is undone and the document is exactly as it was. The agent never has to untangle a half-applied edit.

In the recorded session, the third operation targeted a node that does not exist. The server refused it, left the revision unchanged, and said how to fix it.

the batch, as sent

[
  {
    "action": "table",
    "operation": "updateCell",
    "target": "t_002",
    "rowIndex": 1,
    "columnIndex": 2,
    "text": "$99M"
  },
  {
    "action": "style",
    "target": "2A8D004A",
    "bold": true
  },
  {
    "action": "replace",
    "target": "DEADBEEF",
    "text": "This node does not exist."
  }
]

execute_batch failed: Error: Node DEADBEEF not found in AST

03 · Save

A broken file never reaches the disk.

Edits go into a working copy. save_document validates the whole package against the Word schema first. If something is wrong, nothing is written, and the error says where and what to do next.

In the recorded session the agent set a colour to not-a-color. The edit was accepted into the working copy, the save was refused, and the file on disk was byte-for-byte the same afterwards (the same hash, e910274a1878, before and after). The agent fixed the colour from the remedy and the next save succeeded.

save_document, refused

{
  "ok": false,
  "code": "E_VALIDATION",
  "message": "E_VALIDATION: save blocked: package invalid at /w:document[1]/w:body[1]/w:p[3]/w:r[8]/w:rPr[1]/w:color[1] (8 errors, showing first): The 'http://sche…",
  "remedy": "Fix the flagged operations (re-inspect TOON, correct hex/half-point/twips values) and retry save_document."
}

04 · Undo

Every save is a revision. Go back to any.

History works like version control. You can list the saved revisions, preview what a revert would change, restore an earlier one, and re-apply it if you change your mind. A revert is itself a new revision, so nothing is ever lost by undoing.

get_document_history
List saved revisions, newest first.
preview_revert
See what a revert would change before doing it.
revert_document
Restore an earlier saved revision as a new one.
redo_document
Re-apply a revision that was reverted.

05 · Contain

It works in the folder you allow, and nowhere else.

You start the server with --allowed-dir. Reads and writes are limited to the folders you list, so an agent cannot wander into the rest of your disk.

Before a document leaves your hands, sanitize_document strips authors, comments, tracked revisions, metadata and personal data.

shell

npx -y @attentionform/astra-mcp-server --allowed-dir ./documents

06 · See

The agent looks at its own pages.

visual_inspect renders pages and returns them as images. A model that can see the result catches a table that spills or a heading orphaned at the bottom of a page, before you do. The pages in the gallery on the home page were built and rendered this way.

Rendered page 1 of the recorded board report

Rendered page 2 of the recorded board report

Rendered page 3 of the recorded board report

Give your agent a Word engine it can trust.

One line to start. Your documents stay in your folder.

Connect your agent See the gallery