{
  "markdown": "# Word AI\n\n<!-- mcp-name: io.github.flyfish-dev/word-ai -->\n\n| Language | Preview |\n| --- | --- |\n| [English](README.md) | Structure-preserving Word DOCX editing MCP server with a .NET Open XML backend and Office.js live sessions. |\n| [中文](README.zh-CN.md) | 面向 AI Agent 的 Word DOCX 结构稳定编辑；支持 .NET 后端、Office.js 会话和安全 PatchSet。 |\n\n**Structure-preserving Word (DOCX) editing for AI agents.**\n\nWord 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.\n\n## Why Word AI\n\nAI 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:\n\n- Agents generate constrained `PatchSet` operations.\n- The local engine applies targeted OOXML/Open XML edits.\n- Every write goes through assessment, dry-run, backup, validation, audit, and diff.\n- The Office.js add-in provides a Word taskpane for anchor governance and human-in-the-loop workflows.\n\n## Key Features\n\n- **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.\n- **PatchSet-only writes**. No full document rebuilds, no Markdown/HTML round-trips, and no direct source overwrite by default.\n- **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.\n- **Content-control first editing** using stable Word content control tags such as `WORD-AI:SRS:1.0:overview`.\n- **Strong preconditions** with `source_sha256`, `expected_old_sha256`, and `expected_old_text`.\n- **Structure validation** for package parts, content controls, tables, paragraphs, fields, comments, images, revisions, and protected body blocks.\n- **Python MCP facade and bridge runtime** for local agent integration, path policy, session queues, and distribution compatibility.\n- **.NET 8 Open XML SDK engine** as the authoritative offline DOCX transaction backend, using a packaged native binary or Release DLL when available.\n- **Single-file standalone binaries and quickstart bundles** for no-clone, no-venv, no-.NET-SDK offline DOCX editing and one-command Agent Skill installation.\n- **Office.js taskpane** for Word-side anchors, PatchSet preview, dry-run, apply, and open-document content-control editing with hash checks.\n- **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.\n- **Local HTTP bridge** secured by a local token and localhost-only CORS for Office add-in workflows.\n\n## Architecture\n\n```text\nCodex / Agent / MCP Client\n        |\n        v\nWord AI MCP Server\n        |\n        +--> Python MCP facade / read indexes / Office bridge\n        +--> .NET Open XML SDK backend for offline PatchSet transactions\n        +--> Office bridge HTTP API\n        +--> File-backed Word session command queue\n        |\n        v\nOriginal DOCX -> PatchSet -> Candidate DOCX -> Validation -> Output DOCX + Audit JSON + Diff\n```\n\nThe 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.\n\n## Quick Start\n\nUse the most native distribution path your agent host supports:\n\n1. **MCP Registry / MCPB first**: install the MCP server from the official MCP Registry using server name `io.github.flyfish-dev/word-ai`.\n2. **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.\n3. **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_*`.\n4. **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.\n5. **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.\n\nMCP Registry details:\n\n- Server name: `io.github.flyfish-dev/word-ai`\n- Registry metadata: [server.json](server.json)\n- MCPB package: `https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb`\n- Registry latest API: `https://registry.modelcontextprotocol.io/v0.1/servers/io.github.flyfish-dev%2Fword-ai/versions/latest`\n\nFast local setup with the standalone quickstart bundle:\n\n```bash\ntar -xzf word-ai-quickstart-0.8.6-osx-arm64.tar.gz\ncd word-ai-quickstart-0.8.6-osx-arm64\n\n./word-ai install-skill\n./word-ai codex-config --output .wordai/codex-config.toml\n./word-ai mcp --root \"$PWD\" --allow-root \"$HOME/Downloads\" --allow-root \"$HOME/Documents\"\n```\n\nChoose 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.\n\nInstall the Skill and full local runtime:\n\n```bash\ngit clone https://github.com/flyfish-dev/word-ai.git\ncd word-ai\n\nbash scripts/install.sh\nbash scripts/start.sh\n```\n\nThis 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.\n\nInstall or refresh only the Agent Skill:\n\n```bash\npython3 scripts/install_agent_skills.py\n```\n\nFor browser-only taskpane debugging:\n\n```bash\nbash scripts/start.sh --http\n```\n\nOn Windows PowerShell:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File scripts\\install.ps1\npowershell -ExecutionPolicy Bypass -File scripts\\start.ps1\n```\n\nFor a readiness check:\n\n```bash\n.venv/bin/word-ai --root \"$PWD\" doctor\n```\n\nDeveloper checks:\n\n```bash\nPYTHONPATH=. .venv/bin/python scripts/run_smoke_test.py\nPYTHONPATH=. .venv/bin/python scripts/run_structure_regression.py\nPYTHONPATH=. .venv/bin/python scripts/run_outline_regression.py\nPYTHONPATH=. .venv/bin/python scripts/run_engine_selection_regression.py\n```\n\nBuild the .NET engine:\n\n```bash\ndotnet --version  # requires .NET SDK 8\ndotnet build dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj -c Release\nscripts/publish_dotnet.sh           # current host RID in dist/native/<rid>\nscripts/publish_dotnet.sh --all     # all supported release RIDs\nPYTHONPATH=. .venv/bin/python scripts/run_dotnet_regression.py\n```\n\n## Offline Engine Selection\n\nOffline file transactions use the .NET Open XML backend by default when it is available. Selection order is:\n\n1. `WORD_AI_DOTNET_EXE` or a packaged native executable under `native/<rid>/` or `dist/native/<rid>/`.\n2. `WORD_AI_DOTNET_DLL` or the local Release DLL at `dotnet/WordAi.OpenXml/bin/Release/net8.0/WordAi.OpenXml.dll`.\n3. Local source project via `dotnet run --project dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj`.\n4. Python OOXML fallback only when .NET is unavailable and `WORD_AI_ENGINE=auto`.\n\nMCPB 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.\n\nControl 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.\n\nBuild the Office add-in:\n\n```bash\ncd office-addin\nnpm install\nnpm run build\n```\n\n## Agent Skill Auto-Install\n\nWord 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:\n\n- Codex official user skills: `~/.agents/skills/word-ai`\n- Codex app compatibility skills: `~/.codex/skills/word-ai`\n- Claude Code personal skills: `~/.claude/skills/word-ai`\n- Existing compatible clients when detected: Cursor, Windsurf, GitHub Copilot, and OpenClaw skill folders\n\nInstall or refresh only the skills:\n\n```bash\npython3 scripts/install_agent_skills.py\n```\n\nAdvanced targets:\n\n```bash\npython3 scripts/install_agent_skills.py --agents all\npython3 scripts/install_agent_skills.py --project\npython3 scripts/install_agent_skills.py --dry-run\n```\n\nAfter 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.\n\n## Global MCP Distribution\n\nWord 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:\n\n- MCP server name: `io.github.flyfish-dev/word-ai`\n- MCPB package: `https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb`\n- Registry metadata: [server.json](server.json)\n- Publishing guide: [MCP Registry Publishing](docs/REGISTRY_PUBLISHING.md)\n- Standalone and quickstart guide: [Distribution](docs/DISTRIBUTION.md)\n\nLocal container smoke test:\n\n```bash\ndocker build -t word-ai:local .\ndocker run --rm -i \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$HOME/Downloads:/documents/Downloads\" \\\n  word-ai:local\n```\n\nThe 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.\n\n## Secondary npm Channel\n\nnpm 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.\n\nRecommended scoped package:\n\n```bash\nnpm exec --yes --package @flyfish-dev/word-ai -- word-ai-mcp --root \"$PWD\" --allow-root \"$HOME/Downloads\"\nnpm exec --yes --package @flyfish-dev/word-ai -- word-ai --root \"$PWD\" doctor\n```\n\nUnscoped compatibility package:\n\n```bash\nnpx -y word-ai-mcp --root \"$PWD\"\nnpm exec --yes --package word-ai-mcp -- word-ai --root \"$PWD\" doctor\nnpm exec --yes --package word-ai-mcp -- word-ai-mcp --root \"$PWD\"\n```\n\nAfter a global install, the same commands are available directly:\n\n```bash\nnpm install -g @flyfish-dev/word-ai\nword-ai --root \"$PWD\" doctor\nword-ai-mcp --root \"$PWD\" --allow-root \"$HOME/Downloads\"\n```\n\nThe 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.\n\n## Use With Codex MCP\n\nThe installer writes a ready-to-merge MCP configuration snippet:\n\n```bash\ncat .wordai/codex-config.toml\n```\n\nAdd it to your Codex MCP config. The generated snippet includes write-tool approval gates. A minimal manual version is:\n\n```toml\n[mcp_servers.word_ai]\ncommand = \"/absolute/path/to/word-ai/.venv/bin/python\"\nargs = [\n  \"-m\", \"word_ai_mcp.server\",\n  \"--root\", \"/absolute/path/to/word-ai\",\n  \"--allow-root\", \"/Users/you/Downloads\",\n  \"--allow-root\", \"/Users/you/Documents\"\n]\nenabled = true\nstartup_timeout_sec = 30\n\n[mcp_servers.word_ai.env]\nPYTHONPATH = \"/absolute/path/to/word-ai\"\n```\n\nSecondary npm-based Codex setup, for hosts that cannot install from MCP Registry/MCPB yet:\n\n```toml\n[mcp_servers.word_ai]\ncommand = \"npm\"\nargs = [\n  \"exec\",\n  \"--yes\",\n  \"--package\",\n  \"@flyfish-dev/word-ai\",\n  \"--\",\n  \"word-ai-mcp\",\n  \"--root\",\n  \"/absolute/path/to/workspace\",\n  \"--allow-root\",\n  \"/Users/you/Downloads\",\n  \"--allow-root\",\n  \"/Users/you/Documents\"\n]\nenabled = true\nstartup_timeout_sec = 60\n```\n\nYou can replace `@flyfish-dev/word-ai` with the unscoped compatibility package `word-ai-mcp` in the npm-based Codex config.\n\n`--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.\n\nRecommended approval policy for write tools:\n\n- `docx_dry_run_patchset`\n- `docx_apply_patchset`\n- `docx_backup`\n- `docx_restore_backup`\n- `docx_rollback`\n- `word_session_apply_patchset`\n- `word_session_wrap_selection`\n- `word_session_rollback`\n- sidecar export tools\n\nExample prompt:\n\n```text\nUse 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.\n```\n\nFor the currently open Word document, load the Office add-in, connect the bridge, then ask Codex:\n\n```text\nUse 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.\n```\n\n## Office.js Bridge And Live Word Sessions\n\nThe easiest path is:\n\n```bash\nbash scripts/start.sh\n```\n\nFor manual startup, start the local bridge:\n\n```bash\nPYTHONPATH=. .venv/bin/python -m word_ai_mcp.server_http \\\n  --root \"$PWD\" \\\n  --host 127.0.0.1 \\\n  --port 8765\n```\n\nStart the taskpane:\n\n```bash\ncd office-addin\nnpm run dev\n```\n\nThen 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.\n\nOnce connected inside Word, the taskpane registers a live session under `.wordai/sessions`. Codex can then use:\n\n- `word_session_list`\n- `word_session_snapshot`\n- `word_session_read_content_control`\n- `word_session_preview_patchset`\n- `word_session_apply_patchset`\n- `word_session_wrap_selection`\n- `word_session_rollback`\n- `word_session_command_status`\n\nThis 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.\n\n## OfficeCLI Compatibility Policy\n\nWord 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.\n\nThe 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_*`.\n\nWord 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.\n\n## Safe Editing Workflow\n\n```text\ndocx_health_check\n  -> docx_map / docx_list_anchors / docx_list_content_controls\n  -> docx_read_content_control / docx_read_table_cell / docx_read_paragraph\n  -> generate PatchSet with source_sha256 and expected_old_sha256\n  -> docx_assess_patchset\n  -> docx_dry_run_patchset\n  -> docx_backup\n  -> docx_apply_patchset\n  -> docx_validate / docx_compare_structure\n  -> docx_text_diff\n```\n\n## Documentation\n\n- [Documentation Index](docs/README.md)\n- [Getting Started](docs/GETTING_STARTED.md)\n- [Distribution](docs/DISTRIBUTION.md)\n- [Word AI Codex Skill](skills/word-ai/SKILL.md)\n- [Architecture](docs/ARCHITECTURE.en.md)\n- [Tool Contract](docs/TOOL_CONTRACT.md)\n- [Security Design](docs/SECURITY.en.md)\n- [QA Report](docs/QA_REPORT.md)\n- [Validation Matrix](docs/VALIDATION_MATRIX.md)\n- [MCP Registry Publishing](docs/REGISTRY_PUBLISHING.md)\n- [v0.8.6 Changelog](docs/CHANGELOG_V086.md)\n- [v0.8.5 Changelog](docs/CHANGELOG_V085.md)\n- [v0.8.4 Changelog](docs/CHANGELOG_V084.md)\n- [v0.8.3 Changelog](docs/CHANGELOG_V083.md)\n- [v0.8.1 Changelog](docs/CHANGELOG_V081.md)\n- [v0.8.0 Changelog](docs/CHANGELOG_V080.md)\n- [v0.7.1 Changelog](docs/CHANGELOG_V071.md)\n- [v0.7 Changelog](docs/CHANGELOG_V07.md)\n\n## Repository Status\n\nWord 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.\n\n## License\n\nGNU Affero General Public License v3.0 or later (`AGPL-3.0-or-later`). See [LICENSE](LICENSE).\n",
  "bytes": 19081,
  "sha": "5cab5433bd034b0b213db68c76d0abec3c5b0dca509a41890648a85e276d6a8d",
  "repo_slug": "flyfish-dev/word-ai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_flyfish_dev_word_ai_db658c79/readme"
}