Connect ASTra to your agent.

Claude Desktop

Add the server to claude_desktop_config.json, then restart Claude. The file is here:

• 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",
        "/path/to/your/documents"
      ]
    }
  }
}

Cursor and Windsurf

Put this in .cursor/mcp.json in your project (Windsurf uses its own MCP settings file with the same shape).

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

Claude Code

claude mcp add astra -- npx -y @attentionform/astra-mcp-server --allowed-dir "$PWD"

Any other MCP client

ASTra speaks MCP over stdio. Launch npx -y @attentionform/astra-mcp-server --allowed-dir <folder> as the server command. These are the tools your agent gets:

• open_document: Open a .docx into a session and get a session ID.
• inspect_document: Read the document as compact rows with node IDs and styles.
• search_content: Find text and get back the node IDs that contain it.
• execute_batch: Apply up to 500 typed operations, all or nothing.
• save_document: Validate, then write the file. A broken package is refused with a remedy.
• close_document: Release a session.
• new_document: Create a blank report or memo.
• compose_document: Build a whole document from Markdown, with charts, tables and callouts.
• export_document: Export to HTML, Markdown or PDF.
• visual_inspect: Render pages so the agent can check its own layout.
• 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.
• validate_document: Run the save-time checks without writing anything.
• get_stats: Word, paragraph, table and image counts, cheaply.
• sanitize_document: Strip authors, comments, revisions, metadata and personal data.
• normalize_document: Repair known structural problems, then re-validate.
• import_document: Bring a Markdown file on disk into the open session.

Tell your agent how to use it

A short starting prompt. Most clients do not need it, but it helps weaker models stay on the rails.

You have the ASTra MCP tools. Open the .docx I name with open_document, read it with inspect_document (compact), make changes with execute_batch using node IDs from the inspect output, then save_document. If a call returns an error, read the "remedy" field and fix the operation. Do not retry the same call unchanged.

Command line

For scripts, CI and quick checks. Add --json for machine-readable output. Exit code 0 is success, 1 is an operational failure, 2 is a usage error.

npx -y @attentionform/astra create report.docx --template report
npx -y @attentionform/astra inspect report.docx --fidelity compact
npx -y @attentionform/astra batch report.docx --append "Key milestones for Q4."
npx -y @attentionform/astra validate report.docx
npx -y @attentionform/astra export report.docx --format pdf -o report.pdf
npx -y @attentionform/astra sanitize report.docx clean.docx --client-safe

Install globally with npm install -g @attentionform/astra to get the short astra command.

TypeScript engine

npm install @attentionform/astra-engine

import { DocxParser, OperationEngine } from '@attentionform/astra-engine';
import * as fs from 'node:fs';

const parser = new DocxParser(fs.readFileSync('document.docx'));
const ast = await parser.getAST();
const engine = new OperationEngine(ast, parser);

const result = await engine.executeBatch({
  operations: [
    { action: 'replace', target: ast.sections[0].nodes[0].id, text: 'Executive Strategic Review (Q4)' },
    { action: 'insert', type: 'paragraph', anchor: ast.sections[0].nodes[0].id, position: 'after', text: 'Net revenue increased by 28%.' },
  ],
});

if (result.success) {
  fs.writeFileSync('document_updated.docx', parser.rezip()); // validates, then serialises
} else {
  console.error(result.errors);
}