Word AI

Structure-preserving Word (DOCX) editing for AI agents.

Word AI is an open-source MCP server and Office.js bridge for safe, auditable, incremental editing of Microsoft Word documents. It is designed for Codex, OpenAI Agents, and other MCP clients that need to edit .docx files without rebuilding the document or damaging styles, numbering, tables, images, fields, headers, footers, and relationships.

Why Word AI

AI systems are good at generating text, but Word documents are structured packages. A naive DOCX-to-Markdown-to-DOCX workflow can break numbering, styles, tables, images, fields, references, and layout. Word AI keeps the original DOCX structure as the source of truth:

• Agents generate constrained PatchSet operations.
• The local engine applies targeted OOXML/Open XML edits.
• Every write goes through assessment, dry-run, backup, validation, audit, and diff.
• The Office.js add-in provides a Word taskpane for anchor governance and human-in-the-loop workflows.

Key Features

• 63 MCP tools for DOCX inspection, anchors, headings, paragraphs, tables, fields, images, comments, revisions, PatchSet planning, dry-run, apply, validation, rollback, diff, live Word session editing, and optional read-only OfficeCLI evidence.
• PatchSet-only writes. No full document rebuilds, no Markdown/HTML round-trips, and no direct source overwrite by default.
• Agent-friendly PatchSet normalization for common aliases such as operation, target_tag, new_text, text_sha256, and camelCase operation names, while preserving the canonical safety gates.
• Content-control first editing using stable Word content control tags such as WORD-AI:SRS:1.0:overview.
• Strong preconditions with source_sha256, expected_old_sha256, and expected_old_text.
• Structure validation for package parts, content controls, tables, paragraphs, fields, comments, images, revisions, and protected body blocks.
• Python MCP facade and bridge runtime for local agent integration, path policy, session queues, and distribution compatibility.
• .NET 8 Open XML SDK engine as the authoritative offline DOCX transaction backend, using a packaged native binary or Release DLL when available.
• Single-file standalone binaries and quickstart bundles for no-clone, no-venv, no-.NET-SDK offline DOCX editing and one-command Agent Skill installation.
• Office.js taskpane for Word-side anchors, PatchSet preview, dry-run, apply, and open-document content-control editing with hash checks.
• Live Word session tools (word_session_*) so Codex can read, preview, apply, and roll back edits in the currently open Word document through Office.js.
• Local HTTP bridge secured by a local token and localhost-only CORS for Office add-in workflows.

Architecture

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

The Office.js taskpane is the Word session layer. It creates and lists content controls, connects to the local bridge, registers the current Word document as a live session, polls commands queued by Codex, executes supported PatchSet operations through Office.js, and returns audit/rollback data.

Quick Start

Use the most native distribution path your agent host supports:

1. MCP Registry / MCPB first: install the MCP server from the official MCP Registry using server name io.github.flyfish-dev/word-ai.
2. Standalone quickstart for the lowest local setup cost: download the current-platform GitHub Release bundle when you want one executable that can run MCP, install the Skill, and generate Codex config without a source checkout.
3. Agent Skill next: install the word-ai Skill so Codex, Claude Code, and compatible agents know when to choose offline docx_* versus live word_session_*.
4. Local source install for full Word sessions: use this when you need the Office.js taskpane, localhost bridge, .NET Open XML regression path, or development workflow.
5. npm as a secondary channel: use npm only when your MCP host cannot consume MCP Registry/MCPB yet, or when you want a no-clone stdio server command.

MCP Registry details:

• Server name: io.github.flyfish-dev/word-ai
• Registry metadata: server.json
• MCPB package: https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
• Registry latest API: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.flyfish-dev%2Fword-ai/versions/latest

Fast local setup with the standalone quickstart bundle:

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"

Choose the artifact matching your platform: linux-x64, linux-arm64, osx-arm64, osx-x64, win-x64, or win-arm64. See Distribution for the complete release asset policy.

Install the Skill and full local runtime:

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

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

This installs the Python MCP facade, builds the Office.js taskpane, builds the .NET Open XML backend when .NET SDK 8 is available, writes .wordai/codex-config.toml, and installs the word-ai skill into Codex, Claude Code, and detected compatible agent clients.

Install or refresh only the Agent Skill:

python3 scripts/install_agent_skills.py

For browser-only taskpane debugging:

bash scripts/start.sh --http

On Windows PowerShell:

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

For a readiness check:

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

Developer checks:

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

Build the .NET engine:

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

Offline Engine Selection

Offline file transactions use the .NET Open XML backend by default when it is available. Selection order is:

1. WORD_AI_DOTNET_EXE or a packaged native executable under native/<rid>/ or dist/native/<rid>/.
2. WORD_AI_DOTNET_DLL or the local Release DLL at dotnet/WordAi.OpenXml/bin/Release/net8.0/WordAi.OpenXml.dll.
3. Local source project via dotnet run --project dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj.
4. Python OOXML fallback only when .NET is unavailable and WORD_AI_ENGINE=auto.

MCPB includes self-contained native backends for osx-arm64, osx-x64, linux-x64, linux-arm64, linux-musl-x64, linux-musl-arm64, win-x64, and win-arm64. Standalone quickstart bundles are built for standard hosted platforms: linux-x64, linux-arm64, osx-arm64, osx-x64, win-x64, and win-arm64, with the matching Open XML backend linked into the single-file executable. Word AI detects the current RID, including Linux glibc vs musl for native backend loading, and loads the matching binary automatically. The npm launcher keeps the package small: on first run it downloads the current-platform quickstart bundle from GitHub Releases and executes the bundled word-ai. Advanced deployments can override detection with WORD_AI_DOTNET_RID, WORD_AI_DOTNET_EXE, or WORD_AI_DOTNET_NATIVE_DIR; set WORD_AI_NPM_USE_SOURCE_BOOTSTRAP=1 only when you want the legacy Python venv npm path.

Control it with WORD_AI_ENGINE=auto|dotnet|python, or pass engine to docx_assess_patchset, docx_dry_run_patchset, docx_apply_patchset, and docx_validate. Use WORD_AI_ENGINE=dotnet in production to fail fast instead of silently falling back.

Build the Office add-in:

cd office-addin
npm install
npm run build

Agent Skill Auto-Install

Word AI ships a formal word-ai Agent Skill. This is the preferred way to teach agents the safe workflow, even when the MCP server is installed through the MCP Registry. The installer copies the Skill into the locations that current agent clients scan automatically:

• Codex official user skills: ~/.agents/skills/word-ai
• Codex app compatibility skills: ~/.codex/skills/word-ai
• Claude Code personal skills: ~/.claude/skills/word-ai
• Existing compatible clients when detected: Cursor, Windsurf, GitHub Copilot, and OpenClaw skill folders

Install or refresh only the skills:

python3 scripts/install_agent_skills.py

Advanced targets:

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

After installation, start a new agent session or restart the client if the skill does not appear immediately. The skill can then be invoked directly as word-ai / $word-ai, or selected implicitly when a DOCX editing task mentions Word, Office.js, content controls, PatchSet, validation, rollback, or audit.

Global MCP Distribution

Word AI is published for discovery through the official MCP Registry and MCPB distribution. Prefer this channel for MCP host installation because it carries standardized server metadata, versioning, transport details, and provenance:

• MCP server name: io.github.flyfish-dev/word-ai
• MCPB package: https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
• Registry metadata: server.json
• Publishing guide: MCP Registry Publishing
• Standalone and quickstart guide: Distribution

Local container smoke test:

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

The MCP Registry release uses a public MCPB artifact for one-click-friendly local server installation. The standalone quickstart bundle is the lowest-friction local command path because it embeds the Python facade, dependencies, current-platform .NET Open XML backend, schemas, and Skill template in one executable. The MCPB package requires Python 3.10+ and bootstraps a local virtual environment on first run. The Dockerfile remains available for local or self-hosted builds. For full Office.js live-session editing, use the local source install path because the Word taskpane and localhost bridge must run on the user's machine.

Secondary npm Channel

npm is a convenience fallback for clients that do not yet consume MCP Registry/MCPB packages, for CI smoke tests, and for quick no-clone stdio server startup. It is not the primary discovery channel.

Recommended scoped package:

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

Unscoped compatibility package:

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"

After a global install, the same commands are available directly:

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

The first npm run downloads the current-platform quickstart bundle from GitHub Releases, caches it under the user cache, and executes the bundled standalone word-ai. No Python venv, pip install, or separate Open XML backend download is required on the default npm path. Set WORD_AI_NPM_USE_SOURCE_BOOTSTRAP=1 only when you explicitly want the legacy Python venv bootstrap path.

Use With Codex MCP

The installer writes a ready-to-merge MCP configuration snippet:

cat .wordai/codex-config.toml

Add it to your Codex MCP config. The generated snippet includes write-tool approval gates. A minimal manual version is:

[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"

Secondary npm-based Codex setup, for hosts that cannot install from MCP Registry/MCPB yet:

[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

You can replace @flyfish-dev/word-ai with the unscoped compatibility package word-ai-mcp in the npm-based Codex config.

--root is the primary workspace for relative paths and Word AI sidecars. Repeat --allow-root for external document folders you want Codex to edit, such as Downloads, Documents, or a team project folder. The installer-generated .wordai/codex-config.toml includes common user document folders automatically.

Recommended approval policy for write tools:

• 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
• sidecar export tools

Example prompt:

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.

For the currently open Word document, load the Office add-in, connect the bridge, then ask 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 Bridge And Live Word Sessions

The easiest path is:

bash scripts/start.sh

For manual startup, start the local bridge:

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

Start the taskpane:

cd office-addin
npm run dev

Then sideload office-addin/manifest.xml in Word. The taskpane runs at https://localhost:3100/taskpane.html by default and proxies /bridge/* to the local bridge. The bridge prints a local token at startup. Use that token in the taskpane.

Once connected inside Word, the taskpane registers a live session under .wordai/sessions. Codex can then use:

• 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

This path edits the currently open Word document through Office.js. word_session_apply_patchset performs a live preflight against the open document, checks expected_old_sha256, applies supported content-control operations, returns an audit object, and generates a rollback PatchSet. The offline DOCX path still uses docx_* tools and the OOXML/Open XML validator.

OfficeCLI Compatibility Policy

Word AI can optionally use OfficeCLI as auxiliary evidence for read-only or low-risk checks: view html, view screenshot, view issues, query --json, and validate. OfficeCLI mutation commands such as set, add, remove, raw-set, batch, and merge are not part of the default Word AI workflow unless they are wrapped by Word AI PatchSet, dry-run, audit, rollback, and explicit approval gates.

The MCP server exposes this integration only through allowlisted wrappers: officecli_view_html, officecli_view_screenshot, officecli_view_issues, officecli_query, and officecli_validate. If OfficeCLI is not installed, these tools return available=false and the core Word AI workflow continues to use docx_* and word_session_*.

Word AI borrows useful OfficeCLI design ideas such as schema/help-first usage, semantic paths, watch/render evidence, template merge concepts, and dump/batch inspection. The authoritative write model remains Word AI PatchSet.

Safe Editing Workflow

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

Documentation

• Documentation Index
• Getting Started
• Distribution
• Word AI Codex Skill
• Architecture
• Tool Contract
• Security Design
• QA Report
• Validation Matrix
• MCP Registry Publishing
• v0.8.6 Changelog
• v0.8.5 Changelog
• v0.8.4 Changelog
• v0.8.3 Changelog
• v0.8.1 Changelog
• v0.8.0 Changelog
• v0.7.1 Changelog
• v0.7 Changelog

Repository Status

Word AI is currently a local-first developer tool. It is suitable for controlled DOCX editing experiments, agent integration, and internal workflow pilots. For production remote MCP deployments, use proper MCP Streamable HTTP transport, authentication, network controls, audit storage, and render/visual diff infrastructure.

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.