Word AI

Word AI

言語	プレビュー
English	.NET Open XML バックエンドと Office.js のライブセッションを備えた、構造を保持する Word DOCX 編集 MCP サーバーです。
中文	面向 AI Agent 的 Word DOCX 结构稳定编辑；支持 .NET 后端、Office.js 会话和安全 PatchSet。

AI エージェント向けの、構造を保持する Word（DOCX）編集機能です。

Word AI は、Microsoft Word ドキュメントを安全かつ監査可能な方法で段階的に編集するための、オープンソースの MCP サーバーおよび Office.js ブリッジです。Codex、OpenAI Agents、その他の MCP クライアントが、ドキュメントを再構築したり、スタイル、番号付け、表、画像、フィールド、ヘッダー、フッター、リレーションシップを損なったりすることなく、.docx ファイルを編集できるよう設計されています。

Word AI を選ぶ理由

AI システムはテキストの生成を得意としていますが、Word ドキュメントは構造化されたパッケージです。単純な DOCX から Markdown、さらに DOCX へ変換するワークフローでは、番号付け、スタイル、表、画像、フィールド、参照、レイアウトが壊れる可能性があります。Word AI は、元の DOCX 構造を信頼できる情報源として保持します。

• エージェントは制約付きの PatchSet 操作を生成します。
• ローカルエンジンが対象を絞った OOXML/Open XML 編集を適用します。
• すべての書き込みで、評価、ドライラン、バックアップ、検証、監査、差分確認を行います。
• Office.js アドインは、アンカー管理と人間が介在するワークフローのための Word 作業ウィンドウを提供します。

主な機能

• DOCX の検査、アンカー、見出し、段落、表、フィールド、画像、コメント、変更履歴、PatchSet の計画、ドライラン、適用、検証、ロールバック、差分確認、Word ライブセッションの編集、オプションの読み取り専用 OfficeCLI 証跡に対応する63 個の MCP ツール。
• PatchSet のみで書き込みます。ドキュメント全体の再構築、Markdown/HTML との相互変換、デフォルトでのソースへの直接上書きは行いません。
• operation、target_tag、new_text、text_sha256 などの一般的な別名や camelCase の操作名を正規化しつつ、正規の安全性チェックを維持する、エージェント向けの PatchSet 正規化。
• WORD-AI:SRS:1.0:overview などの安定した Word コンテンツコントロールタグを使った、コンテンツコントロール優先の編集。
• source_sha256、expected_old_sha256、expected_old_text による強力な事前条件。
• パッケージパーツ、コンテンツコントロール、表、段落、フィールド、コメント、画像、変更履歴、保護された本文ブロックの構造検証。
• ローカルエージェントとの連携、パスのポリシー、セッションキュー、配布の互換性を実現するPython MCP ファサードとブリッジランタイム。
• 権威あるオフライン DOCX トランザクションバックエンドとして動作し、利用可能な場合はパッケージ化されたネイティブバイナリまたは Release DLL を使用する**.NET 8 Open XML SDK エンジン**。
• リポジトリのクローン、venv、.NET SDK が不要なオフライン DOCX 編集と、ワンコマンドでの Agent Skill インストールに対応する単一ファイルのスタンドアロンバイナリとクイックスタートバンドル。
• Word 側のアンカー、PatchSet のプレビュー、ドライラン、適用、ハッシュチェック付きの開いているドキュメントのコンテンツコントロール編集に対応するOffice.js 作業ウィンドウ。
• Codex が Office.js を通じて、現在開いている Word ドキュメント内の編集を読み取り、プレビュー、適用、ロールバックできるようにするWord ライブセッションツール（word_session_*）。
• Office アドインのワークフロー向けに、ローカルトークンと localhost のみを許可する CORS で保護されたローカル HTTP ブリッジ。

アーキテクチャ

Codex / Agent / MCP Client
        |
        v
Word AI MCP Server
        |
        +--> Python MCP facade / read indexes / Office bridge
        +--> .NET Open XML SDK backend for offline PatchSet transactions
        +--> Office bridge HTTP API
        +--> File-backed Word session command queue
        |
        v
Original DOCX -> PatchSet -> Candidate DOCX -> Validation -> Output DOCX + Audit JSON + Diff

Office.js 作業ウィンドウは Word セッションレイヤーです。コンテンツコントロールの作成と一覧表示、ローカルブリッジへの接続、現在の Word ドキュメントのライブセッションとしての登録、Codex がキューに入れたコマンドのポーリング、Office.js によるサポート対象の PatchSet 操作の実行、監査データとロールバックデータの返却を行います。

クイックスタート

エージェントホストがサポートする、最も標準的な配布方法を使用してください。

1. まず MCP Registry / MCPB：公式 MCP Registry から、サーバー名 io.github.flyfish-dev/word-ai の MCP サーバーをインストールします。
2. ローカル環境のセットアップを最小限にするなら、スタンドアロンのクイックスタート：ソースをチェックアウトせずに、MCP の実行、Skill のインストール、Codex 設定の生成ができる単一の実行ファイルが必要な場合は、現在のプラットフォーム向けの GitHub Release バンドルをダウンロードします。
3. 次に Agent Skill：word-ai Skill をインストールすると、Codex、Claude Code、および互換性のあるエージェントが、オフラインの docx_* と、ライブセッションの word_session_* のどちらを選択すべきか判断できるようになります。
4. Word セッションをすべて利用するなら、ローカルソースからインストール：Office.js taskpane、localhost ブリッジ、.NET Open XML 回帰テスト経路、または開発ワークフローが必要な場合に使用します。
5. npm は補助的な配布方法：MCP ホストがまだ MCP Registry/MCPB を利用できない場合、または clone なしで実行できる stdio サーバーコマンドが必要な場合にのみ npm を使用します。

MCP Registry の詳細：

• サーバー名：io.github.flyfish-dev/word-ai
• Registry のメタデータ：server.json
• MCPB パッケージ：https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
• Registry 最新版 API：https://registry.modelcontextprotocol.io/v0.1/servers/io.github.flyfish-dev%2Fword-ai/versions/latest

スタンドアロンのクイックスタートバンドルを使った、すばやいローカルセットアップ：

tar -xzf word-ai-quickstart-0.8.6-osx-arm64.tar.gz
cd word-ai-quickstart-0.8.6-osx-arm64

./word-ai install-skill
./word-ai codex-config --output .wordai/codex-config.toml
./word-ai mcp --root "$PWD" --allow-root "$HOME/Downloads" --allow-root "$HOME/Documents"

お使いのプラットフォームに合ったアーティファクトを選択してください：linux-x64、linux-arm64、osx-arm64、osx-x64、win-x64、または win-arm64。リリースアセットのポリシー全体については、配布を参照してください。

Skill とローカルランタイム全体をインストール：

git clone https://github.com/flyfish-dev/word-ai.git
cd word-ai

bash scripts/install.sh
bash scripts/start.sh

これにより、Python MCP ファサードをインストールし、Office.js taskpane をビルドし、.NET SDK 8 が利用可能な場合は .NET Open XML バックエンドをビルドして、.wordai/codex-config.toml を書き込み、Codex、Claude Code、および検出された互換性のあるエージェントクライアントに word-ai スキルをインストールします。

Agent Skill のみをインストールまたは更新：

python3 scripts/install_agent_skills.py

ブラウザーのみで taskpane をデバッグする場合：

bash scripts/start.sh --http

Windows PowerShell の場合：

powershell -ExecutionPolicy Bypass -File scripts\install.ps1
powershell -ExecutionPolicy Bypass -File scripts\start.ps1

準備状況の確認：

.venv/bin/word-ai --root "$PWD" doctor

開発者向けチェック：

PYTHONPATH=. .venv/bin/python scripts/run_smoke_test.py
PYTHONPATH=. .venv/bin/python scripts/run_structure_regression.py
PYTHONPATH=. .venv/bin/python scripts/run_outline_regression.py
PYTHONPATH=. .venv/bin/python scripts/run_engine_selection_regression.py

.NET エンジンをビルド：

dotnet --version  # requires .NET SDK 8
dotnet build dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj -c Release
scripts/publish_dotnet.sh           # current host RID in dist/native/<rid>
scripts/publish_dotnet.sh --all     # all supported release RIDs
PYTHONPATH=. .venv/bin/python scripts/run_dotnet_regression.py

オフラインエンジンの選択

オフラインのファイルトランザクションでは、.NET Open XML バックエンドが利用可能な場合、デフォルトで使用されます。選択順序は次のとおりです。

1. WORD_AI_DOTNET_EXE、または native/<rid>/ もしくは dist/native/<rid>/ にあるパッケージ化済みのネイティブ実行ファイル。
2. WORD_AI_DOTNET_DLL、またはローカルの Release DLL dotnet/WordAi.OpenXml/bin/Release/net8.0/WordAi.OpenXml.dll。
3. dotnet run --project dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj を使ったローカルソースプロジェクト。
4. .NET が利用できず、WORD_AI_ENGINE=auto の場合に限り、Python OOXML フォールバックを使用します。

MCPB には、osx-arm64、osx-x64、linux-x64、linux-arm64、linux-musl-x64、linux-musl-arm64、win-x64、および win-arm64 向けの、自己完結型ネイティブバックエンドが含まれています。スタンドアロンのクイックスタートバンドルは、標準的なホストプラットフォーム向けにビルドされており、対象は linux-x64、linux-arm64、osx-arm64、osx-x64、win-x64、および win-arm64 です。対応する Open XML バックエンドは、単一ファイルの実行ファイルにリンクされています。Word AI は、ネイティブバックエンドの読み込み時に Linux の glibc と musl の違いも含め、現在の RID を検出し、対応するバイナリを自動的に読み込みます。npm ランチャーはパッケージを小さく保つため、初回実行時に GitHub Releases から現在のプラットフォーム向けクイックスタートバンドルをダウンロードし、同梱の word-ai を実行します。高度なデプロイでは、WORD_AI_DOTNET_RID、WORD_AI_DOTNET_EXE、または WORD_AI_DOTNET_NATIVE_DIR を使って検出方法を上書きできます。従来の Python venv を使った npm 経路が必要な場合にのみ、WORD_AI_NPM_USE_SOURCE_BOOTSTRAP=1 を設定してください。

WORD_AI_ENGINE=auto|dotnet|python で制御するか、docx_assess_patchset、docx_dry_run_patchset、docx_apply_patchset、および docx_validate に engine を渡してください。本番環境では WORD_AI_ENGINE=dotnet を使用すると、暗黙のフォールバックをせずに、エラーを即座に返します。

Office アドインをビルド：

cd office-addin
npm install
npm run build

エージェントスキルの自動インストール

Word AI には、正式な word-ai エージェントスキルが用意されています。MCP サーバーを MCP Registry 経由でインストールする場合でも、エージェントに安全なワークフローを習得させるには、この方法が推奨されます。インストーラーは、現在のエージェントクライアントが自動的にスキャンする次の場所にスキルをコピーします。

• Codex 公式ユーザースキル：~/.agents/skills/word-ai
• Codex アプリ互換スキル：~/.codex/skills/word-ai
• Claude Code 個人用スキル：~/.claude/skills/word-ai
• 検出された既存の互換クライアント：Cursor、Windsurf、GitHub Copilot、OpenClaw のスキルフォルダー

スキルのみをインストールまたは更新します。

python3 scripts/install_agent_skills.py

詳細なインストール先：

python3 scripts/install_agent_skills.py --agents all
python3 scripts/install_agent_skills.py --project
python3 scripts/install_agent_skills.py --dry-run

インストール後、スキルがすぐに表示されない場合は、新しいエージェントセッションを開始するか、クライアントを再起動してください。その後、word-ai / $word-ai として直接呼び出すか、Word、Office.js、コンテンツコントロール、PatchSet、検証、ロールバック、監査に言及する DOCX 編集タスクで暗黙的に選択できます。

MCP のグローバル配布

Word AI は、公式 MCP Registry と MCPB 配布を通じて公開されており、検索できます。標準化されたサーバーメタデータ、バージョン情報、トランスポートの詳細、来歴情報が含まれるため、MCP ホストへのインストールにはこの方法を推奨します。

• MCP サーバー名：io.github.flyfish-dev/word-ai
• MCPB パッケージ：https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
• Registry メタデータ：server.json
• 公開ガイド：MCP Registry への公開
• スタンドアロン版およびクイックスタートガイド：配布

ローカルコンテナーのスモークテスト：

docker build -t word-ai:local .
docker run --rm -i \
  -v "$PWD:/workspace" \
  -v "$HOME/Downloads:/documents/Downloads" \
  word-ai:local

MCP Registry リリースでは、ローカルサーバーをワンクリックで簡単にインストールできるよう、公開 MCPB アーティファクトを使用しています。スタンドアロンのクイックスタートバンドルは、Python ファサード、依存関係、現在のプラットフォーム用の .NET Open XML バックエンド、スキーマ、スキルテンプレートを1つの実行ファイルにまとめているため、ローカルでコマンドを実行する最も手軽な方法です。MCPB パッケージには Python 3.10 以降が必要で、初回実行時にローカル仮想環境がセットアップされます。Dockerfile は、ローカルビルドやセルフホスト可能なビルドにも引き続き利用できます。Office.js のライブセッションで完全な編集機能を使うには、Word のタスクペインと localhost ブリッジをユーザーのマシン上で実行する必要があるため、ローカルソースのインストール方法を使用してください。

npm のセカンダリ配布チャネル

npm は、MCP Registry／MCPB パッケージをまだ利用していないクライアント、CI のスモークテスト、リポジトリをクローンせずに stdio サーバーをすばやく起動する場合の代替手段です。主要な検索チャネルではありません。

推奨されるスコープ付きパッケージ：

npm exec --yes --package @flyfish-dev/word-ai -- word-ai-mcp --root "$PWD" --allow-root "$HOME/Downloads"
npm exec --yes --package @flyfish-dev/word-ai -- word-ai --root "$PWD" doctor

スコープなしの互換パッケージ：

npx -y word-ai-mcp --root "$PWD"
npm exec --yes --package word-ai-mcp -- word-ai --root "$PWD" doctor
npm exec --yes --package word-ai-mcp -- word-ai-mcp --root "$PWD"

グローバルインストール後は、同じコマンドをそのまま利用できます。

npm install -g @flyfish-dev/word-ai
word-ai --root "$PWD" doctor
word-ai-mcp --root "$PWD" --allow-root "$HOME/Downloads"

npm での初回実行時に、GitHub Releases から現在のプラットフォーム用クイックスタートバンドルがダウンロードされ、ユーザーキャッシュに保存された後、同梱のスタンドアロン版 word-ai が実行されます。デフォルトの npm 経由の方法では、Python の venv、pip によるインストール、Open XML バックエンドの個別ダウンロードは不要です。従来の Python venv セットアップ方法を明示的に使用する場合にのみ、WORD_AI_NPM_USE_SOURCE_BOOTSTRAP=1 を設定してください。

Codex MCP での使用

インストーラーは、すぐにマージできる MCP 設定スニペットを書き込みます。

cat .wordai/codex-config.toml

Codex MCP 設定に追加してください。生成されるスニペットには、書き込みツールの承認ゲートが含まれています。最小限の手動設定例は次のとおりです。

[mcp_servers.word_ai]
command = "/absolute/path/to/word-ai/.venv/bin/python"
args = [
  "-m", "word_ai_mcp.server",
  "--root", "/absolute/path/to/word-ai",
  "--allow-root", "/Users/you/Downloads",
  "--allow-root", "/Users/you/Documents"
]
enabled = true
startup_timeout_sec = 30

[mcp_servers.word_ai.env]
PYTHONPATH = "/absolute/path/to/word-ai"

MCP Registry/MCPB からまだインストールできないホスト向けの、npm ベースの代替 Codex 設定です。

[mcp_servers.word_ai]
command = "npm"
args = [
  "exec",
  "--yes",
  "--package",
  "@flyfish-dev/word-ai",
  "--",
  "word-ai-mcp",
  "--root",
  "/absolute/path/to/workspace",
  "--allow-root",
  "/Users/you/Downloads",
  "--allow-root",
  "/Users/you/Documents"
]
enabled = true
startup_timeout_sec = 60

npm ベースの Codex 設定では、@flyfish-dev/word-ai をスコープなしの互換パッケージ word-ai-mcp に置き換えることができます。

--root は、相対パスと Word AI サイドカーの基準となるプライマリーワークスペースです。Codex に編集させたい外部ドキュメントフォルダー（Downloads、Documents、チームのプロジェクトフォルダーなど）には、--allow-root を繰り返し指定してください。インストーラーが生成する .wordai/codex-config.toml には、一般的なユーザーのドキュメントフォルダーが自動的に含まれます。

書き込みツールには、次の承認ポリシーを推奨します。

• docx_dry_run_patchset
• docx_apply_patchset
• docx_backup
• docx_restore_backup
• docx_rollback
• word_session_apply_patchset
• word_session_wrap_selection
• word_session_rollback
• サイドカーのエクスポートツール

プロンプトの例：

Use word_ai to inspect examples/sample_contract.docx, list content controls, read WORD-AI:SRS:1.0:overview, and prepare a PatchSet. Run assess and dry-run before applying.

現在開いている Word ドキュメントでは、Office アドインを読み込み、ブリッジに接続してから、Codex に次のように依頼します。

Use word_ai to list active Word sessions, read WORD-AI:SRS:1.0:overview from the live Word session, preview a PatchSet through Office.js, then apply it to the open document and return the audit plus rollback PatchSet.

Office.js ブリッジと Word ライブセッション

最も簡単な方法は次のとおりです。

bash scripts/start.sh

手動で起動する場合は、ローカルブリッジを起動します。

PYTHONPATH=. .venv/bin/python -m word_ai_mcp.server_http \
  --root "$PWD" \
  --host 127.0.0.1 \
  --port 8765

タスクペインを起動します。

cd office-addin
npm run dev

次に、Word で office-addin/manifest.xml をサイドロードします。タスクペインはデフォルトで https://localhost:3100/taskpane.html で実行され、/bridge/* をローカルブリッジにプロキシします。ブリッジは起動時にローカルトークンを出力します。そのトークンをタスクペインで使用してください。

Word 内で接続すると、タスクペインは .wordai/sessions にライブセッションを登録します。Codex では、次のツールを使用できます。

• word_session_list
• word_session_snapshot
• word_session_read_content_control
• word_session_preview_patchset
• word_session_apply_patchset
• word_session_wrap_selection
• word_session_rollback
• word_session_command_status

この方法では、Office.js を介して現在開いている Word ドキュメントを編集します。word_session_apply_patchset は、開いているドキュメントに対してライブの事前チェックを行い、expected_old_sha256 を確認し、サポートされているコンテンツコントロール操作を適用して、監査オブジェクトを返し、ロールバック用の PatchSet を生成します。オフラインの DOCX 処理では引き続き docx_* ツールと OOXML/Open XML バリデーターを使用します。

OfficeCLI 互換性ポリシー

Word AI では、読み取り専用または低リスクのチェックの補助的な証拠として、OfficeCLI を任意で使用できます。対象は view html、view screenshot、view issues、query --json、validate です。set、add、remove、raw-set、batch、merge などの OfficeCLI の変更コマンドは、Word AI PatchSet、ドライラン、監査、ロールバック、明示的な承認ゲートでラップされない限り、Word AI のデフォルトのワークフローには含まれません。

MCP サーバーでは、この連携機能を許可リストに登録されたラッパー（officecli_view_html、officecli_view_screenshot、officecli_view_issues、officecli_query、officecli_validate）を介してのみ公開します。OfficeCLI がインストールされていない場合、これらのツールは available=false を返し、Word AI のコアワークフローでは引き続き docx_* と word_session_* を使用します。

Word AI は、スキーマ／ヘルプを優先する使い方、セマンティックパス、監視／レンダリングによる証拠、テンプレートのマージ概念、ダンプ／バッチによる検査など、有用な OfficeCLI の設計上のアイデアを取り入れています。書き込みの正式なモデルは、引き続き Word AI PatchSet です。

安全な編集ワークフロー

docx_health_check
  -> docx_map / docx_list_anchors / docx_list_content_controls
  -> docx_read_content_control / docx_read_table_cell / docx_read_paragraph
  -> generate PatchSet with source_sha256 and expected_old_sha256
  -> docx_assess_patchset
  -> docx_dry_run_patchset
  -> docx_backup
  -> docx_apply_patchset
  -> docx_validate / docx_compare_structure
  -> docx_text_diff

ドキュメント

• ドキュメント一覧
• はじめに
• 配布
• Word AI Codex スキル
• アーキテクチャ
• ツールコントラクト
• セキュリティ設計
• QA レポート
• 検証マトリックス
• MCP レジストリへの公開
• v0.8.6 変更履歴
• v0.8.5 変更履歴
• v0.8.4 変更履歴
• v0.8.3 変更履歴
• v0.8.1 変更履歴
• v0.8.0 変更履歴
• v0.7.1 変更履歴
• v0.7 変更履歴

リポジトリの状況

Word AI は現在、ローカルファーストの開発者向けツールです。管理された DOCX 編集の実験、エージェントとの統合、社内ワークフローの試験運用に適しています。本番環境でリモート MCP をデプロイする場合は、適切な MCP Streamable HTTP トランスポート、認証、ネットワーク制御、監査ログの保存、レンダリング／ビジュアル差分のためのインフラを使用してください。

ライセンス

GNU Affero General Public License v3.0 or later（AGPL-3.0-or-later）。LICENSE を参照してください。