ASTra

@attentionform/astra-mcp-server

ASTra ドキュメントエンジン向けの公式 Model Context Protocol（MCP）サーバーです。

@attentionform/astra-mcp-server は、標準入出力（stdio）を介して、19 種類の包括的なエージェントインターフェースを提供します。Claude Desktop、Cursor、Windsurf、Cline などの AI コーディングアシスタントや、カスタム LLM エージェントが、トランザクションの整合性を保ち、スキーマを破損させることなく、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 エージェントに追加できます。

1. Claude Desktop

Claude Desktop の設定ファイルに ASTra を追加します。

• 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}"]

スキーマの最新状態（ツールの変更時）

提供される各ツールには、バージョンスタンプ付きの JSON コピーが schemas/mcp/ に含まれます（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	いいえ	行の区切り位置で適用するトークン予算の上限です（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 が表示されます。最大 5 件のセルアドレス（例：t_001:r3c1）が含まれ、replace、style、namedStyle、clearFormat、hyperlink、bookmark、comment の target として渡せます。セルアドレスは、inspect_document がグリッドを表示する形式に従って <tableId>:r<row>c<col> となり、行と列の番号は 1 から始まります。複数の段落があるセルの場合は :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

変更されたすべての XML パーツを ECMA-376 スキーマに照らして検証し、変更をディスクにコミットします。

パラメーター：

パラメーター	型	必須	説明
sessionId	string	はい	アクティブなセッション識別子です。
outPath	string	いいえ	保存先のパス（デフォルトは元のセッションパス）です。
message	string	いいえ	ドキュメント履歴に記録するコミットログメッセージです。
author	string	いいえ	ドキュメント履歴に記録する作成者名です。
allowMacros	boolean	いいえ	保存時にマクロを保持することを明示するマクロポリシーです。
stripMacros	boolean	いいえ	保存時にマクロを除去することを明示するマクロポリシーです。
strict	boolean	いいえ	ファイルを開いた時点ですでに存在していたエラーも含め、バリデーターのすべてのエラーを拒否します。また、w14:paraId を共有する段落も拒否します（通常の保存では段落の ID が再割り当てされます）。デフォルト：オフ。または、サーバーフラグ --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.、および網掛けされた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 chars）。
author	string	いいえ	差し戻しコミットの作成者識別子（≤ 100 chars）。
reason	string	いいえ	差し戻しログの監査理由文字列（≤ 500 chars）。

戻り値： { ok: true, sessionId, path, revertedToCommit, revision }

---

redo_document

最後の差し戻しによって取り消されたバージョンを再適用します。

パラメーター：

パラメーター	型	必須	説明
sessionId	string	はい	アクティブなセッション識別子。
message	string	いいえ	やり直しコミットのメッセージ（≤ 500 chars）。
author	string	いいえ	やり直しコミットの作成者識別子（≤ 100 chars）。
reason	string	いいえ	やり直しログの監査理由文字列（≤ 500 chars）。

戻り値： { 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

トークン消費を抑えながら、単語数、段落数、表数、画像数、ページ数を集計します。

パラメーター：

パラメーター	型	必須	説明
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	いいえ	テキストとコメント内の潜在的な PII パターンを編集して伏せます。
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 で結果が記録されるため、steps: 1 を指定した revert_document を実行すると、修復前の状態に戻ります。

パラメーター：

パラメーター	型	必須	説明
sessionId	string	はい	アクティブなセッション識別子です。

戻り値： { ok: true, sessionId, revision, dirty, normalized, remaining, rolledBack, preStateCommit?, validation }。normalized には、書き換えられたすべての内容が列挙されます。remaining は残っているバリデーターエラーの数です。バリデーターが実行されなかった場合は -1 です。rolledBack は [{ rule, reason }] です。

---

推奨されるエージェントのライフサイクルフロー

AI エージェントは、次の標準的な実行順序に従う必要があります。

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：外部依存関係（PDF エクスポートに必要な LibreOffice など）が PATH に見つかりません。

---

ローカル開発

このリポジトリから @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 をご覧ください。各バージョンはリリースから 4 年後に Apache-2.0 に移行します。LICENSE を参照するか、商用ライセンスについて [email protected] までお問い合わせください。