word-ai

# Word AI

<!-- mcp-name: io.github.flyfish-dev/word-ai -->

| Language | Preview |
| --- | --- |
| [English](README.md) | Structure-preserving Word DOCX editing MCP server with a .NET Open XML backend and Office.js live sessions. |
| [中文](README.zh-CN.md) | 面向 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.

## 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

```text
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](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:

```bash
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](docs/DISTRIBUTION.md) for the complete release asset policy.

Install the Skill and full local runtime:

```bash
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:

```bash
python3 scripts/install_agent_skills.py
```

For browser-only taskpane debugging:

```bash
bash scripts/start.sh --http
```

On Windows PowerShell:

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

For a readiness check:

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

Developer checks:

```bash
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:

```bash
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:

```bash
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:

```bash
python3 scripts/install_agent_skills.py
```

Advanced targets:

```bash
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 sel