Word AI

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/ 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/ / or dist/native/ /.
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" doct