Structure-preserving Word DOCX editing MCP server and Office.js bridge for AI agents.
| Language | Preview |
|---|---|
| English | Structure-preserving Word DOCX editing MCP server with a .NET Open XML backend and Office.js live sessions. |
| 中文 | 面向 AI Agent 的 Word DOCX 结构稳定编辑；支持 .NET 后端、Office.js 会话和安全 PatchSet。 |
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.
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:
PatchSet operations.operation, target_tag, new_text, text_sha256, and camelCase operation names, while preserving the canonical safety gates.WORD-AI:SRS:1.0:overview.source_sha256, expected_old_sha256, and expected_old_text.word_session_*) so Codex can read, preview, apply, and roll back edits in the currently open Word document through Office.js.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.
Use the most native distribution path your agent host supports:
io.github.flyfish-dev/word-ai.word-ai Skill so Codex, Claude Code, and compatible agents know when to choose offline docx_* versus live word_session_*.MCP Registry details:
io.github.flyfish-dev/word-aihttps://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpbhttps://registry.modelcontextprotocol.io/v0.1/servers/io.github.flyfish-dev%2Fword-ai/versions/latestFast 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 file transactions use the .NET Open XML backend by default when it is available. Selection order is:
WORD_AI_DOTNET_EXE or a packaged native executable under native/<rid>/ or dist/native/<rid>/.WORD_AI_DOTNET_DLL or the local Release DLL at dotnet/WordAi.OpenXml/bin/Release/net8.0/WordAi.OpenXml.dll.dotnet run --project dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj.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
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:
~/.agents/skills/word-ai~/.codex/skills/word-ai~/.claude/skills/word-aiInstall 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.
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:
io.github.flyfish-dev/word-aihttps://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpbLocal 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.
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.
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_patchsetdocx_apply_patchsetdocx_backupdocx_restore_backupdocx_rollbackword_session_apply_patchsetword_session_wrap_selectionword_session_rollbackExample 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.
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_listword_session_snapshotword_session_read_content_controlword_session_preview_patchsetword_session_apply_patchsetword_session_wrap_selectionword_session_rollbackword_session_command_statusThis 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.
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.
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 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.
GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.
This listing does not have a supported local package template. Use the maintainer’s documentation for its hosted endpoint, authentication, and client-specific setup. No install command has been inferred.
https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpbotherWord AI works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.