Docx Editing

Editing .docx Files with Safe-DOCX

Safe-DOCX is a local MCP server for surgically editing existing .docx files. It preserves formatting, generates tracked-changes redlines, and — once installed — runs entirely on the local filesystem with zero network activity.

Source Code and Audit

Safe-DOCX is fully open source (MIT license). Review the complete source before installing:

All security claims below are verifiable by reading the source.

Runtime Requirements

Safe-DOCX requires these binaries to be available on the host:

| Binary | Minimum version | Why | |--------|-----------------|-----| | node | 18.0.0 | Authoritative version from packages/safe-docx/package.json engines field | | npx | Bundled with npm | Used by the recommended MCP connector to launch the server |

If you prefer not to use npx, see Offline / Pinned Installation below for alternatives.

Safety Model

Safe-DOCX's safety model has two distinct phases: install time (when the package is fetched) and runtime (when the MCP server is running).

Install-Time Behavior (network required, one-time)

Runtime Behavior (zero network)

Offline / Pinned Installation

For high-security environments where npx auto-fetch is unacceptable, install the package manually and pin the version:

# Option 1: Pin a specific version globally
npm install -g @usejunior/safe-docx@0.9.0
Then configure your MCP client to invoke it by path:
command: "safe-docx"
args: []
Option 2: Vendor the package into your project
npm pack @usejunior/safe-docx@0.9.0
Inspect the tarball, then install it from disk:
npm install -g ./usejunior-safe-docx-0.9.0.tgz
Option 3: Build from source (most auditable)
git clone https://github.com/UseJunior/safe-docx.git
cd safe-docx
git checkout 
npm ci
npm run build
npm link packages/safe-docx

After any of these, your MCP client config becomes:

{
  "mcpServers": {
    "safe-docx": {
      "command": "safe-docx",
      "args": []
    }
  }
}

Using command: "safe-docx" (the installed binary) instead of command: "npx" eliminates the install-time network fetch on every invocation.

Always pin the version

Even with npx, you can pin the version to prevent unexpected updates:

{
  "mcpServers": {
    "safe-docx": {
      "command": "npx",
      "args": ["-y", "@usejunior/safe-docx@0.9.0"]
    }
  }
}

Before upgrading, review the changelog: https://github.com/UseJunior/safe-docx/blob/main/CHANGELOG.md

When to Use This Skill

Use Safe-DOCX when you need to:

Not for From-Scratch Generation

Safe-DOCX edits already-existing .docx files — it does not create documents from blank. For new document generation, use a template-filling workflow (e.g. OpenAgreements). Safe-DOCX can refine generated docs downstream.

Quick Start

1. read_file(file_path="~/doc.docx")        → see paragraphs + _bk_* IDs
2. grep(file_path="~/doc.docx", patterns=["target phrase"])  → find paragraph IDs
3. replace_text(session_id, target_paragraph_id, old_string, new_string, instruction)
4. save(session_id, save_to_local_path="~/doc-edited.docx")

Core Workflow: Read, Locate, Edit, Save

Step 1 — Read. Call read_file with format: "toon" (token-efficient table) to see paragraphs and their stable _bk_* IDs.

Step 2 — Locate. Use grep with regex patterns to find target paragraphs. It returns paragraph IDs with surrounding context.

Step 3 — Edit. Use replace_text to swap text within a paragraph, or insert_paragraph to add new paragraphs before/after an anchor.

Step 4 — Save. Call save to write output. Default is save_format: "both" which produces a clean copy and a tracked-changes redline.

Gotchas That Will Bite You

Unique match required

replace_text needs old_string to match exactly one location in the target paragraph. If the text appears multiple times, you get MULTIPLE_MATCHES. Fix: include more surrounding context in old_string.

BAD:  old_string: "the Company"          → 5 matches, fails
GOOD: old_string: "the Company shall indemnify"  → 1 match, succeeds

Footnote markers are display-only

read_file shows footnotes as [^1], [^2], etc., but these markers are not part of the editable text. You cannot search for or replace [^1] via replace_text. To modify footnotes, use the dedicated add_footnote, update_footnote, and delete_footnote tools.

Hyperlinks are read-only

read_file shows links as text, but you cannot create new hyperlinks via replace_text or insert_paragraph. The tag is stripped from new text. Existing hyperlinks are preserved when surrounding text is edited.

Paragraph IDs are session-scoped

The _bk_* bookmark IDs are generated when a document is opened and are tied to that session. Do not store or reuse IDs across sessions. Always re-read the document to get fresh IDs.

Smart text matching

replace_text is tolerant of:

1. read_file / grep  → gather paragraph IDs and text
2. apply_plan(file_path, steps=[
     { step_id: "1", operation: "replace_text", target_paragraph_id, old_string, new_string, instruction },
     { step_id: "2", operation: "insert_paragraph", positional_anchor_node_id, new_string, instruction },
     ...
   ])
3. save(session_id, save_to_local_path)

For MCP server setup instructions (Claude Desktop, Cursor, Claude Code), see CONNECTORS.md.

Feedback

If this skill helped, star us on GitHub: https://github.com/UseJunior/safe-docx On ClawHub: clawhub star usejunior/docx-editing

1. read_file(file_path="~/doc.docx")        → see paragraphs + _bk_* IDs
2. grep(file_path="~/doc.docx", patterns=["target phrase"])  → find paragraph IDs
3. replace_text(session_id, target_paragraph_id, old_string, new_string, instruction)
4. save(session_id, save_to_local_path="~/doc-edited.docx")