ASTra

@attentionform/astra-mcp-server

面向 ASTra 文档引擎的官方 Model Context Protocol（MCP）服务。

@attentionform/astra-mcp-server 通过标准输入/输出（stdio）提供全面的 19 种 Agent 工具接口。它让 AI 编码助手（包括 Claude Desktop、Cursor、Windsurf、Cline 和自定义大模型 Agent）能够检查、查询、修改和导出 Microsoft Word（.docx）文档，同时保证事务完整性且不会破坏架构。

---

快速开始

使用 npx 运行（推荐）

无需安装。通过 --allowed-dir 传入文档目录：

npx -y @attentionform/astra-mcp-server --allowed-dir /path/to/your/documents

安全提示： ASTra 会严格实施目录沙箱限制。服务只会在通过 --allowed-dir（或 ASTRA_EXTRA_DOC_ROOTS 环境变量）明确指定的目录中读取和写入文件。路径必须是绝对路径，且在磁盘上确实存在。指定的文件夹就是完整的边界：系统临时文件夹不会自动添加。指定文件夹本身或其上层目录中的符号链接会被跟随；其下方指向文件夹外部的链接则会被拒绝。

验证。 open_document 会检查文件并报告 valid、invalid、timed-out 或 skipped；它不会拒绝打开文件。若保存操作没有新增验证错误（相较于文件原有错误），则允许保存。服务标志：--strict-validation（也可设为 ASTRA_STRICT_VALIDATION=1）会拒绝所有错误；--open-validation-timeout <ms>（也可设为 ASTRA_OPEN_VALIDATION_TIMEOUT_MS）用于设置打开时的等待时间，默认值为 5000。

宏和大小限制。 open_document 接受 allowMacros（保留宏部件）或 stripMacros（移除宏部件及其所有引用）。防 ZIP 炸弹的上限由环境变量 ASTRA_MAX_RATIO（默认值为 100）和 ASTRA_MAX_UNCOMPRESSED_BYTES 设置。

全局安装

npm install -g @attentionform/astra-mcp-server
astra-mcp-server --allowed-dir /path/to/your/documents

---

客户端集成

添加一段简单的 JSON 配置，即可将 ASTra 接入 AI Agent：

1. Claude Desktop

将 ASTra 添加到 Claude Desktop 配置文件中：

• 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

在项目根目录下创建或编辑 .cursor/mcp.json：

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

3. Windsurf

添加到 Windsurf MCP 配置文件（~/.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 扩展）

在 Cline 的 MCP 设置选项卡中配置：

• 服务名称： astra
• 命令： npx
• 参数： ["-y", "@attentionform/astra-mcp-server", "--allowed-dir", "${workspaceFolder}"]

架构新鲜度（工具变更时）

每个提供的工具都会在 schemas/mcp/ 下附带一份带版本戳的 JSON 副本（x-generated-from 标明服务构建版本）。客户端会缓存这些架构：

• 内存缓存（Claude Desktop 在应用生命周期内缓存，Cursor 和 Zed 按会话缓存）：重启宿主应用以获取新工具。
• 磁盘缓存（以文件形式引入 JSON 副本的配置）：重新运行导出，然后让客户端指向新目录：

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

当所有版本戳都与已安装的服务匹配时，--check-schemas 会以 0 退出；否则会打印过期文件警告并以 1 退出。CI 会在每次推送时重新生成并对比 schemas/mcp/，因此未更新副本的架构变更会导致构建失败。

---

19 种 MCP 工具

ASTra 提供一套完整的 19 种工具，并按功能组织。服务会通过 tools/list 返回全部 19 种工具：

open_document

将 .docx 文件打开到隔离的内存编辑会话中。

参数：

参数	类型	必填	描述
path	string	是	允许目录内 .docx 文件的绝对路径。
sessionId	string	否	服务器生成的会话 ID（不建议提供；仅用于测试）。
summaryOnly	boolean	否	省略或设为 true 时返回精简摘要；设为 false 时包含完整的结构摘要和样式 XML。
allowMacros	boolean	否	按字节原样保留宏部分。
stripMacros	boolean	否	加载时移除宏部分。
author	string	否	本会话中未指定作者的修订和批注所用的默认作者（回退为服务器的 ASTRA_AUTHOR，然后是 ASTra）。操作自身的 author 优先。
validationTimeoutMs	integer	否	打开文件时等待验证器的时长，以毫秒为单位。0 表示跳过检查。默认值为 5000，或使用服务器标志 --open-validation-timeout / ASTRA_OPEN_VALIDATION_TIMEOUT_MS。

返回： { ok: true, sessionId, revision, summary, evicted, validation }。当文件已有验证器错误时，validation 为 { status: "valid" }、{ status: "invalid", preExistingErrors, messages, baselineComparable, note }、{ status: "timed-out" } 或 { status: "skipped" }。

---

inspect_document

使用 Token-Optimized Outline Notation（TOON）检查文档结构。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
fidelity	string	否	"compact"（默认）、"standard" 或 "full"。
sectionId	string	否	将大纲限制在指定章节。
maxTextLength	number	否	将运行文本截断至指定字符数。
offset	number	否	文档节点的分页起始行（默认值：0）。超出最后一个节点的偏移量将被拒绝。
limit	number	否	返回的最大节点行数（默认值：50，最大值：200）。
aroundNode	string	否	检查窗口中心位置的节点 ID。
window	number	否	aroundNode 周围行数的一半（默认值：5）。
maxTokens	number	否	在完整行边界处截断的 Token 预算（200–8000）。
include	array	否	可选的要包含的审阅记录：["comments"]、["revisions"] 或两者。
reviewOffset	number	否	include 列表的起始记录（默认值：0）。对批注和修订分页，但不移动节点窗口。
reviewLimit	number	否	每个 include 列表的记录数（默认值：50；超过 50 的值会限制为 50）。
commentId	number	否	要检查的特定批注 ID。需要 include:["comments"]。
revisionId	number	否	要检查的特定跟踪修订 ID。需要 include:["revisions"]。

返回： { ok: true, sessionId, revision, fidelity, palette, toonText, rowCount }

---

search_content

快速搜索文本，返回匹配的稳定节点 ID 和文本片段。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
query	string	是	搜索查询字符串（1–500 个字符）。
regex	boolean	否	将查询视为正则表达式（默认值：false）。
scope	string	否	搜索范围："body"（默认）、"comments" 或 "all"。

返回： { ok: true, sessionId, matches: [{ id, preview, cells? }], truncated? }。最多返回 50 个匹配项；truncated: true 表示还有更多结果。表格匹配项会列出 cells，最多包含五个单元格地址，例如 t_001:r3c1，可将其作为 replace、style、namedStyle、clearFormat、hyperlink、bookmark 或 comment 的 target。单元格地址格式为 <tableId>:r<row>c<col>，行和列从 1 开始，与 inspect_document 打印网格时一致（包含多个段落的单元格需追加 :p<n>）。

execute_batch

执行包含类型化操作的原子数组，并提供架构验证和回滚保证。

参数：

参数	类型	必需	描述
sessionId	string	是	活动会话标识符。
operations	array	是	包含 1 到 500 个类型化操作对象的数组。
sequential	boolean	否	按顺序依次应用操作（默认值：true）。
rollbackOnError	boolean	否	如果任何操作失败，则回滚整个批次（默认值：true）。
maxSteps	number	否	中止前的最大执行步数。
allowedDir	string	否	读取图像 filePath 的受限目录。
styleGuide	string	否	此批次的样式指南覆盖项（名称或 .md 路径）。

返回： { ok: true, sessionId, appliedCount, revision, createdNodeIds, revisionsPending, revisionsUnresolved?, revisionsRemedy?, revisionResolution? }。revisionsPending 统计所有剩余修订元素的数量（一次移动操作按其中每个修订标记分别计数）。如果某个 trackedChange 操作留下了无法解决的修订，revisionsUnresolved 会统计这些修订的数量，而 revisionsRemedy 会列出类型、节点和原因，而不是重复列出 acceptAll。如果被移除的段落带有书签、批注或失效链接，revisionResolution 还会列出 removedBookmarks、removedComments 和 staleLinks。

---

save_document

根据 ECMA-376 架构验证所有已修改的 XML 部件，并将更改提交到磁盘。

参数：

参数	类型	必需	描述
sessionId	string	是	活动会话标识符。
outPath	string	否	目标路径（默认为原始会话路径）。
message	string	否	文档历史记录的提交日志消息。
author	string	否	文档历史记录中的作者姓名。
allowMacros	boolean	否	明确指定宏策略，以便保存时保留宏。
stripMacros	boolean	否	明确指定宏策略，以便保存时移除宏。
strict	boolean	否	拒绝所有验证器错误，包括文件打开时已存在的错误。也会拒绝共享同一 w14:paraId 的段落，而保存操作通常会对其重新编号。默认关闭；也可通过服务器标志 --strict-validation / ASTRA_STRICT_VALIDATION=1 启用。

返回： { ok: true, sessionId, path, revision, commitOid, validation }。如果文件原本已有验证器错误，而编辑没有新增错误，则 validation 为 { ok: false, tolerated: true, preExistingErrors, introducedErrors: 0, messages }；否则为 { ok: true }。

---

close_document

关闭活动会话并释放所有内存中的资源。

参数：

参数	类型	必需	描述
sessionId	string	是	活动会话标识符。

返回： { ok: true, sessionId }

---

new_document

使用执行模板创建新的 .docx 文件，并将其打开到一个会话中。

参数：

参数	类型	必需	描述
outPath	string	是	允许目录内的目标文件路径。
template	string	否	模板类型："report"、"memo" 或 "blank"（默认值："blank"）。
force	boolean	否	如果文件已存在，则覆盖它（默认值：false）。
styleGuide	string	否	要附加的内置指南名称或指南 .md 路径。
author	string	否	此会话中未指定作者的修订和批注的默认作者（若未设置，则使用服务器的 ASTRA_AUTHOR，再回退到 ASTra）。操作自身的 author 优先。
sessionId	string	否	由服务器生成的会话 ID（不建议提供；仅供测试使用）。

返回： { ok: true, path, sessionId, revision, template, bytes }

---

compose_document

将 Markdown 字符串编译为 OOXML 结构，并将其整洁地应用到文档中。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
markdown	string	是	要编译并应用的 Markdown 源文本。
allowedDir	string	否	用于解析相对图片和图表路径的沙盒目录。
template	string	否	替换 "report"、"memo" 或 "blank" 的种子内容。仅适用于会话中的首次 compose。
styleGuide	string	否	用于设置排版样式的内置指南名称或指南 .md 路径。
dollarMath	boolean	否	将 $...$ 语法视为行内数学表达式（默认值：false）。
anchor	string	否	块的插入位置：节点 ID、"start" 或 "end"（默认值：最后一个节点之后）。
position	string	否	相对于 anchor 的位置："before" 或 "after"（默认值）。

返回值： { ok: true, sessionId, appliedCount, revision, createdNodeIds, persistentIds? }。createdNodeIds（会话中首次 compose 时为 md_0001…，下一次为 md2_0001…，后续依此类推）在整个会话中均有效；persistentIds 将每个新建段落映射到保存文件中对应的 ID，以便重新打开文件后定位（表格会按位置重新编号，因此不会列出）。

---

在当前会话中创建且未更改的内置模板，其示例内容会在 compose 时被替换。如果模板经过编辑、从外部模板加载，或在后续会话中重新打开，compose 会保留其现有内容，并附加新内容。

import_document

在目录沙盒限制下，将磁盘上的 Markdown 文件导入已打开的会话。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
path	string	是	允许目录中的磁盘 Markdown 文件路径。
allowedDir	string	否	用于解析相对图片和图表路径的沙盒目录。
template	string	否	验证模板种子内容的处理方式（"report"、"memo"、"blank"）。
styleGuide	string	否	附加样式指南（内置名称或指南 .md 路径）。
dollarMath	boolean	否	将 $...$ 语法视为行内数学表达式（默认值：false）。

返回值： { ok: true, sessionId, appliedCount, revision }

---

export_document

将当前内存状态渲染为 PDF、HTML 或 Markdown。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
format	string	是	导出格式："pdf"、"html" 或 "markdown"。
outPath	string	否	允许目录中的目标文件路径。
tagged_pdf	boolean	否	仅适用于 PDF：生成带标签（无障碍）的渲染结果（默认值：true）。
tagged	boolean	否	tagged_pdf 的别名。
strict	boolean	否	仅适用于 PDF：遇到预检阻止项时失败关闭（默认值：false）。
imageMode	string	否	仅适用于 Markdown："file"（需要 outPath；将图片提取到资源目录下唯一的代次目录中；提供 outPath 时为默认值）或 "embed"（base64 数据 URI）。
assetPrefix	string	否	仅适用于 Markdown：当 imageMode 为 "file" 时，自定义资源目录名称／前缀。

返回值： { ok: true, format, path, bytes, content }

---

visual_inspect

生成 2D 空间布局遥测数据，并可选择生成无头页面渲染图。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
pages	array	否	要检查/渲染的页码（从 1 开始，最多 4 页）。
withVisual	boolean	否	生成无头渲染图像（默认：false）。
format	string	否	图像格式："png"（默认）或 "jpeg"。
jpegQuality	number	否	JPEG 质量系数（1–100）。
dpi	number	否	渲染分辨率（72–300，默认：150）。
outputDir	string	否	启用 withVisual 时，将图像写入此文件夹（如果不存在则创建），文件名为 <document>-page-<n>.png，供无法读取服务端临时文件夹的客户端使用。必须位于允许的文件夹内，例如文档路径。默认值：服务端临时文件所在文件夹。

返回： { ok: true, sessionId, telemetry, images: [{ page, path }], outDir }

telemetry 中的线框图会显示带有表头和首行的 [TABLE: n cols]、- 和 1. 列表标记，以及用于着色单单元格表格的 [CALLOUT]。

---

get_document_history

获取文档先前提交的版本。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
limit	number	否	要获取的最大提交条目数（默认：20，最多：100）。
offset	number	否	提交日志的分页偏移量。

返回： { ok: true, history: [{ oid, message, author, timestamp }] }

---

preview_revert

模拟回滚，但不应用更改。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
steps	number	否	要回滚的提交数。
commitOid	string	否	要预览还原的特定提交哈希目标。

返回： { ok: true, targetOid, affectedFiles, dirty }

---

revert_document

将文档状态回滚到之前的某个提交，并创建一个仅追加的还原提交。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
steps	number	否	要回滚的提交数。
commitOid	string	否	要还原到的特定提交哈希目标。
discardUnsaved	boolean	否	丢弃未提交的更改（默认：false）。
message	string	否	还原提交消息（≤ 500 个字符）。
author	string	否	还原提交的作者标识符（≤ 100 个字符）。
reason	string	否	还原日志的审计原因字符串（≤ 500 个字符）。

返回： { ok: true, sessionId, path, revertedToCommit, revision }

---

redo_document

重新应用上次还原操作撤销的版本。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。
message	string	否	重做提交消息（≤ 500 个字符）。
author	string	否	重做提交的作者标识符（≤ 100 个字符）。
reason	string	否	重做日志的审计原因字符串（≤ 500 个字符）。

返回： { ok: true, sessionId, revision, commitOid }

---

validate_document

在提交更改前，对会话执行只读 OOXML 架构预检。

参数：

参数	类型	必填	说明
sessionId	string	是	当前活动会话标识符。

返回： { ok: true, sessionId, revision, dirty, validation: { valid, errorCount, errors } }

验证建议：当 validate_document 报告文档无效时，其 normalizeHint 会建议尝试运行 normalize_document，然后重新验证。这只是建议，不代表能够预测修复结果，也不保证文档有效；验证不会运行修复规则来生成此提示。规范化会更改打开的会话；使用 save_document 持久化结果，也可以选择保存到新的输出路径。

---

get_stats

以较低的 Token 开销统计文档中的字数、段落数、表格数、图片数和页数。

参数：

参数	类型	必填	说明
sessionId	string	是	当前活动会话标识符。

返回： { ok: true, sessionId, revision, dirty, words, paragraphs, tables, images, pages }

---

sanitize_document

清除文档会话中的元数据、修订 ID、作者信息和个人身份信息（PII）。除非传入 acceptAllRevisions 或 stripComments，否则会保留修订痕迹和评论，包括每条修订删除内容的文本。CLI 预设（单独使用 sanitize、--client-safe、--metadata-only、--redact-pii）会同时启用这两个选项；此工具不会。CLI 标志 --keep-revisions 和 --keep-comments 可让 CLI 运行时采用与此工具默认行为相同的保留方式。

参数：

参数	类型	必填	说明
sessionId	string	是	当前活动会话标识符。
zeroRetention	boolean	否	清除所有跟踪元数据、修订 ID、作者信息和 EXIF。
purgeRSIDs	boolean	否	清除修订保存 ID（w:rsidR、w:rsidRPr 等）。
purgeAuthors	boolean	否	清除作者身份元数据。
purgeExif	boolean	否	清除嵌入图片的元数据和 EXIF 配置文件。
purgePII	boolean	否	从文本和评论中隐去可能包含个人身份信息的模式。
acceptAllRevisions	boolean	否	清除前接受所有修订痕迹。如果仍存在无法解决的修订标记，或已删除段落的评论线程同时锚定在该段落之外，则拒绝执行并返回 E_VALIDATION（不生成文件）；请添加 stripComments。已接受删除段落的评论会被移除。
stripComments	boolean	否	移除所有评论、评论引用以及每个评论部件（包括评论 ID 和时间戳）。
replacementAuthor	string	否	替换后的作者字符串（≤ 256 个字符）。
allowMacros	boolean	否	清除过程中逐字节保留宏部件。
stripMacros	boolean	否	清除过程中移除宏部件。

返回： { ok: true, sessionId, revision, dirty, removedRSIDs, purgedAuthors, strippedExifBytes, purgedPII, bodyPII, acceptedRevisions, strippedComments, strippedMacros, macroParts, filesTouched, droppedRogue }

---

normalize_document

针对打开会话的规范修复。运行允许列表规范化器（对架构序列排序并规范化标签），然后逐条修复已知的验证器错误类型：元素顺序、小数尺寸、开/关值、智能标签、重复的形状类型以及其他少数错误。若某项修复会更改可见文本或增加验证器错误，则会撤销该修复并列入 rolledBack。此工具不会声称文件有效：remaining 统计剩余的验证器错误数。

如果文档有历史记录仓库，且修复前的状态与最新提交不同，则会先提交该状态（preStateCommit）。下一次 save_document 会记录修复结果，因此执行一次 revert_document 并设置 steps: 1，即可返回修复前的状态。

参数：

参数	类型	必填	描述
sessionId	string	是	活动会话标识符。

返回值： { ok: true, sessionId, revision, dirty, normalized, remaining, rolledBack, preStateCommit?, validation }。normalized 列出所有重写操作。remaining 是剩余的验证器错误数；若验证器未运行，则为 -1。rolledBack 的格式为 [{ rule, reason }]。

---

推荐的 Agent 生命周期流程

AI Agent 应遵循以下标准执行顺序：

open_document (or new_document)
      ↓
inspect_document (get TOON outline & node IDs)
      ↓
search_content (optional: pinpoint exact target text)
      ↓
execute_batch (apply atomic mutations with rollback protection)
      ↓
visual_inspect / export_document (verify visual presentation)
      ↓
save_document (validate ECMA-376 schema & commit to disk)
      ↓
close_document (release session memory)

---

错误处理与补救

当工具操作无法完成时，ASTra 会返回结构化错误详情：

{
  "ok": false,
  "code": "E_VALIDATION",
  "message": "Invalid child element sequence in w:pPr",
  "remedy": "Ensure paragraph property tags follow ISO/IEC 29500 ordering rules.",
  "isError": true
}

常见错误代码

• E_SANDBOX：请求的文件路径位于声明的 --allowed-dir 目录之外。
• E_VALIDATION：操作参数未通过 Zod 架构检查或 OOXML 验证。
• E_SESSION：会话 ID 不存在或已超时。
• E_CONFLICT：操作会覆盖现有文件，但未设置 force: true。
• E_DEPENDENCY：在 PATH 中找不到外部依赖（例如用于导出 PDF 的 LibreOffice）。

---

本地开发

要在此代码仓库中本地运行或调试 @attentionform/astra-mcp-server：

# Build package bundles
npm run build:packages

# Run local MCP server directly with node
node packages/mcp-server/dist/index.js --allowed-dir /path/to/docs

---

许可证

Business Source License 1.1（BUSL-1.1）：源代码可用；个人、教育机构、非营利组织、公共机构、小型组织和小型产品可免费使用（参见 LICENSING.md）；其他生产用途需要商业许可证。计划与价格：https://attentionform.com/pricing。每个版本在发布四年后转为 Apache-2.0。参见 LICENSE，如需商业许可证，请发送邮件至 [email protected]。