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:

• - GitHub: https://github.com/UseJunior/safe-docx
• npm registry: https://www.npmjs.com/package/@usejunior/safe-docx
• Code coverage: Published via Codecov on every release
• Conformance harness: Automated spec coverage tests run in CI on every commit
• No postinstall scripts — verify: npm view @usejunior/safe-docx scripts shows no postinstall or install hooks

All security claims below are verifiable by reading the source.

Runtime Requirements

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

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)

• - npm registry fetch — the recommended connector command npx -y @usejunior/safe-docx downloads the package from registry.npmjs.org on first run. Subsequent runs use the cached copy unless the cache is cleared.
• No postinstall scripts — the package declares no postinstall, preinstall, or install hooks. Verify with npm view @usejunior/safe-docx scripts.
• Provenance — releases are published with npm provenance (--provenance), so you can verify the package was built from the public GitHub repo via GitHub Actions.
• If you need guaranteed offline install — pin a specific version and vendor it locally. See the next section.

Runtime Behavior (zero network)

• - Local-only stdio runtime — the MCP server runs as a child process, never binds a port. Verify: the entry point (src/server.ts) uses StdioServerTransport with no HTTP listener. (source)
• No outbound network calls — at runtime, the package makes zero outbound HTTP requests. Verify: grep -r "fetch\|http\.\|https\.\|net\." packages/safe-docx/src/ returns no matches in application code (test fixtures excluded).
• Path policy — only files under ~/ (home directory) and system temp directories are accessible. Symlinks must resolve to allowed roots.
• Archive guardrails — zip bomb detection and hostile payload rejection protect against malformed .docx inputs.

Offline / Pinned Installation

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

CODEBLOCK0

After any of these, your MCP client config becomes:

CODEBLOCK1

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:

CODEBLOCK2

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:

• - Change clauses or paragraphs in an existing INLINECODE24
• Insert or delete content with formatting preservation
• Add comments or footnotes for reviewers
• Produce a tracked-changes redline from edits
• Compare two .docx files into a redline
• Extract revisions to structured JSON
• Apply layout formatting (spacing, row heights, cell padding)

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

CODEBLOCK3

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

INLINECODE35 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.

CODEBLOCK4

Footnote markers are display-only

INLINECODE39 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

INLINECODE47 shows links as <a href="...">text</a>, but you cannot create new hyperlinks via replace_text or insert_paragraph. The <a> 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

INLINECODE53 is tolerant of:

• - Quote variants: straight ", curly \u201c\u201d, angle \u00ab\u00bb all match each other
• Whitespace differences: multiple spaces, tabs, and line breaks are normalized

This means you can copy text from read_file output and use it in old_string even if the underlying XML uses different quote characters.

Formatting Tags

When writing new_string in replace_text or insert_paragraph, use inline tags to apply formatting:

Tags can be nested: <b><i>bold italic</i></b>. Formatting from the original matched text is preserved for untagged replacement text.

Batch Edits with apply_plan

For 3+ edits on one document, prefer apply_plan over sequential replace_text calls. It validates all steps before applying any, so you get all-or-nothing transactional semantics.

CODEBLOCK5

Insert Paragraphs

INLINECODE69 adds new content before or after an anchor paragraph.

• - position: "BEFORE" or "AFTER" (default "AFTER")
• INLINECODE74: optional _bk_* ID of a paragraph whose formatting you want to clone
• Multi-paragraph: separate with \n\n in new_string (each becomes its own paragraph)

Comments and Footnotes

Comments: add_comment anchors to a paragraph (optionally to a text span via anchor_text). Use get_comments to list, delete_comment to remove. Supports threaded replies via parent_comment_id.

Footnotes: add_footnote inserts a footnote marker in a paragraph (optionally after specific text via after_text). Use get_footnotes, update_footnote, delete_footnote to manage.

Comparing Documents

Two modes:

• - Two files: compare_documents(original_file_path, revised_file_path, save_to_local_path) — produces a redline
• Session edits: compare_documents(session_id) — compares current session state against the original

Use extract_revisions on any document with tracked changes to get structured JSON diffs.

Accepting Tracked Changes

Call accept_changes(session_id) to flatten all tracked changes into a clean document. This removes all revision markup.

Session Behavior

• - Sessions auto-create when you first use file_path with any tool
• Sessions expire after 1 hour of inactivity (each tool call resets the timer)
• Call clear_session to clean up when done
• Documents are normalized on open: format-identical runs are merged and proof-error markers removed, which improves text matching reliability

Layout Formatting

INLINECODE94 applies paragraph spacing, table row height, and cell padding without touching text content. Units are in twips (1/20 of a point) or DXA (1/635 of an inch).

Path Restrictions

By default, only files under ~/ (home directory) and system temp directories are accessible. Symlinks must resolve to allowed roots.

Related Skills

• - Open Agreements (open-agreements) — fill standard legal templates (NDAs, SAFEs, cloud service agreements) and produce signable DOCX files: INLINECODE97
• Outlook Email Management (outlook-email-management) — manage Outlook email with AI agents: INLINECODE99

Connectors

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: INLINECODE100