ASTra

@attentionform/astra-mcp-server

Official Model Context Protocol (MCP) server for the ASTra document engine.

@attentionform/astra-mcp-server exposes a comprehensive, 19-tool agentic interface over standard I/O (stdio). It enables AI coding assistants, including Claude Desktop, Cursor, Windsurf, Cline, and custom LLM agents, to inspect, query, mutate, and export Microsoft Word (.docx) documents with transactional integrity and zero schema corruption.

---

Quickstart

Run with npx (Recommended)

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. 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 (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

npm install -g @attentionform/astra-mcp-server

astra-mcp-server --allowed-dir /path/to/your/documents

---

Client Integration

Add ASTra to your AI agent with a simple JSON snippet:

1. Claude Desktop

Add ASTra to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{

"mcpServers": { "astra": { "command": "npx", "args": [ "-y", "@attentionform/astra-mcp-server", "--allowed-dir", "/absolute/path/to/your/documents" ], "env": { "NODE_ENV": "production" } } } }

2. Cursor IDE

Create or edit .cursor/mcp.json in your project root:

{

"mcpServers": { "astra": { "command": "npx", "args": [ "-y", "@attentionform/astra-mcp-server", "--allowed-dir", "${workspaceFolder}" ] } } }

3. Windsurf

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

{

"mcpServers": { "astra": { "command": "npx", "args": [ "-y", "@attentionform/astra-mcp-server", "--allowed-dir", "/absolute/path/to/your/documents" ] } } }

4. Cline (VS Code Extension)

In Cline's MCP settings tab, configure:

• Server Name: astra
• Command: npx
• Args: ["-y", "@attentionform/astra-mcp-server", "--allowed-dir", "${workspaceFolder}"]

Schema freshness (when tools change)

Every served tool ships a version-stamped JSON copy under schemas/mcp/ (x-generated-from names the server build). Clients cache those shapes:

• Memory caches (Claude Desktop for the app lifespan, Cursor and Zed per session): restart the host app to pick up new tools.
• Disk caches (file-based setups that vendor the JSON copies): re-run the dump, then point the client at the fresh dir:

npx -y @attentionform/astra-mcp-server --dump-schemas ./fresh-schemas

npx -y @attentionform/astra-mcp-server --check-schemas ./fresh-schemas

--check-schemas exits 0 when every stamp matches the installed server and prints a stale-file warning with exit 1 otherwise. CI regenerates and diffs schemas/mcp/ on every push, so a schema change without refreshed copies fails the build.

---

The 19 MCP Tools

ASTra provides a complete set of 19 tools organized by capability. The server returns all 19 tools over tools/list:

open_document

Opens a .docx file into an isolated in-memory editing session.

Parameters:

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" }.

---

inspect_document

Inspects document structure using Token-Optimized Outline Notation (TOON).

Parameters:

Returns: { ok: true, sessionId, revision, fidelity, palette, toonText, rowCount }

---

search_content

Fast text search returning matching stable node IDs and text snippets.

Parameters:

Returns: { ok: true, sessionId, matches: [{ id, preview, cells? }], truncated? }. At most 50 matches are returned; truncated: true says more exist. A table hit lists cells, up to five cell addresses such as t_001:r3c1, that you can pass as the target of replace, style, namedStyle, clearFormat, hyperlink, bookmark or comment. Cell addresses are :r c , 1-based as inspect_document prints the grid (add :p for a cell with several paragraphs).

---

execute_batch

Executes an atomic array of typed operations with schema validation and rollback guarantees.

Parameters:

Returns: { ok: true, sessionId, appliedCount, revision, createdNodeIds, revisionsPending, revisionsUnresolved?, revisionsRemedy?, revisionResolution? }. revisionsPending counts every revision element left (a move counts as each of its markers). After a trackedChange that left revisions it could not resolve, revisionsUnresolved counts them and revisionsRemedy lists kind, node and reason instead of repeating acceptAll. revisionResolution also lists removedBookmarks, removedComments and staleLinks when a removed paragraph carried them.

---

save_document

Validates all modified XML parts against ECMA-376 schema and commits changes to disk.

Parameters:

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 }.

---

close_document

Closes the active session and releases all in-memory resources.

Parameters:

Returns: { ok: true, sessionId }

---

new_document

Creates a fresh .docx file from an executive template and opens it into a session.

Parameters:

| 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 `AST