@attentionform/astra-mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -16,7 +16,11 @@ No installation required. Pass your document directory via `--allowed-dir`:
 npx -y @attentionform/astra-mcp-server --allowed-dir /path/to/your/documents
 ```
 
-> **Security Note:** ASTra enforces strict directory sandboxing. The server will only read and write files within directories explicitly declared via `--allowed-dir` (or the `ASTRA_EXTRA_DOC_ROOTS` environment variable). The path must be absolute and exist on disk.
+> **Security Note:** ASTra enforces strict directory sandboxing. The server will only read and write files within directories explicitly declared via `--allowed-dir` (or the `ASTRA_EXTRA_DOC_ROOTS` environment variable). The path must be absolute and exist on disk. The named folders are the whole boundary: the system temp folder is not added. A symbolic link at or above a named folder is followed; a link below it that points outside it is refused.
+
+**Validation.** `open_document` checks the file and reports `valid`, `invalid`, `timed-out` or `skipped`; it never refuses the open. A save is allowed when it adds no validator error beyond the ones the file had. Server flags: `--strict-validation` (also `ASTRA_STRICT_VALIDATION=1`) refuses every error; `--open-validation-timeout <ms>` (also `ASTRA_OPEN_VALIDATION_TIMEOUT_MS`) sets the wait at open, default 5000.
+
+**Macros and size limits.** `open_document` takes `allowMacros` (keep macro parts) or `stripMacros` (remove the parts and every reference to them). The zip-bomb ceilings are `ASTRA_MAX_RATIO` (default 100) and `ASTRA_MAX_UNCOMPRESSED_BYTES`, read from the environment.
 
 ### Global Installation
 
@@ -132,8 +136,9 @@ Opens a `.docx` file into an isolated in-memory editing session.
 | `allowMacros` | `boolean` | No | Preserve macro parts byte-for-byte. |
 | `stripMacros` | `boolean` | No | Strip macro parts upon loading. |
 | `author` | `string` | No | Default author for tracked changes and comments in this session that do not name one (falls back to the server's `ASTRA_AUTHOR`, then `ASTra`). An operation's own `author` wins. |
+| `validationTimeoutMs` | `integer` | No | How long to wait for the validator when the file is opened, in milliseconds. `0` skips the check. Default 5000, or the server flag `--open-validation-timeout` / `ASTRA_OPEN_VALIDATION_TIMEOUT_MS`. |
 
-**Returns:** `{ ok: true, sessionId, revision, summary, evicted }`
+**Returns:** `{ ok: true, sessionId, revision, summary, evicted, validation }`. `validation` is `{ status: "valid" }`, `{ status: "invalid", preExistingErrors, messages, baselineComparable, note }` when the file already has validator errors, `{ status: "timed-out" }` or `{ status: "skipped" }`.
 
 ---
 
@@ -201,8 +206,9 @@ Validates all modified XML parts against ECMA-376 schema and commits changes to
 | `author` | `string` | No | Author name for document history. |
 | `allowMacros` | `boolean` | No | Explicit macro policy to keep macros on save. |
 | `stripMacros` | `boolean` | No | Explicit macro policy to strip macros on save. |
+| `strict` | `boolean` | No | Refuse every validator error, including errors the file already had when it was opened. Also refuses paragraphs that share a `w14:paraId`, which a save otherwise renumbers. Default: off, or the server flag `--strict-validation` / `ASTRA_STRICT_VALIDATION=1`. |
 
-**Returns:** `{ ok: true, sessionId, path, revision, commitOid }`
+**Returns:** `{ ok: true, sessionId, path, revision, commitOid, validation }`. When the file already had validator errors and the edit added none, `validation` is `{ ok: false, tolerated: true, preExistingErrors, introducedErrors: 0, messages }`; otherwise `{ ok: true }`.
 
 ---
 
@@ -252,6 +258,8 @@ Compiles a Markdown string into OOXML structures and applies them cleanly to the
 
 ---
 
+An unchanged built-in template created in the current session has its sample content replaced when composed. If the template was edited, loaded from an external template, or reopened in a later session, compose preserves its existing content and appends the new content.
+
 ### `import_document`
 Ingests an on-disk Markdown file into an open session under directory sandboxing.
 
@@ -281,6 +289,8 @@ Renders the current in-memory state to PDF, HTML, or Markdown.
 | `tagged_pdf` | `boolean` | No | PDF only: tagged (accessible) render (default: `true`). |
 | `tagged` | `boolean` | No | Alias of `tagged_pdf`. |
 | `strict` | `boolean` | No | PDF only: fail closed on preflight blockers (default: `false`). |
+| `imageMode` | `string` | No | Markdown only: `"file"` (requires `outPath`; extracts images into a unique generation under the asset directory, default when `outPath` is provided) or `"embed"` (base64 data URI). |
+| `assetPrefix` | `string` | No | Markdown only: custom asset directory name/prefix when `imageMode` is `"file"`. |
 
 **Returns:** `{ ok: true, format, path, bytes, content }`
 
@@ -414,14 +424,16 @@ Scrub metadata, revision IDs, authors, comments, and PII from a document session
 ---
 
 ### `normalize_document`
-Canonical repair for an open session with schema sequence sorts and tag normalizations.
+Canonical repair for an open session. Runs the allowlist normalizer (schema sequence sorts and tag normalizations), then repairs known validator error kinds one rule at a time: element order, decimal sizes, on/off values, smart tags, duplicate shape types and a few others. A repair that changes the visible text or adds a validator error is dropped and listed in `rolledBack`. The tool does not claim the file is valid: `remaining` counts the validator errors left.
+
+When the document has a history repository and the state before the repairs differs from the head, that state is committed first (`preStateCommit`). The next `save_document` records the result, so one `revert_document` with `steps: 1` returns to the state before the repairs.
 
 **Parameters:**
 | Parameter | Type | Required | Description |
 |---|---|:---:|---|
 | `sessionId` | `string` | Yes | Active session identifier. |
 
-**Returns:** `{ ok: true, sessionId, revision, dirty, normalized, validation: { valid: true } }`
+**Returns:** `{ ok: true, sessionId, revision, dirty, normalized, remaining, rolledBack, preStateCommit?, validation }`. `normalized` lists every rewrite. `remaining` is the number of validator errors left, or `-1` when the validator did not run. `rolledBack` is `[{ rule, reason }]`.
 
 ---