Docx Editing

Surgically edit existing (brownfield) .docx files with formatting preservation and tracked changes via the Safe-DOCX MCP server. Use when user says "edit thi...

Security Scan

The skill's requirements and instructions are consistent with a local .docx editing MCP connector that is installed from the npm registry; the main residual risk is the one-time npm install/fetch (supply-chain) which the SKILL.md acknowledges and provides pinned/offline alternatives for.

Purpose & Capability

Name/description (Docx Editing via Safe‑DOCX) align with what the instructions request: Node/npm usage and running an MCP stdio server. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

Runtime instructions are limited to launching the local MCP server (npx or installed binary), accessing .docx files under the user's home and system temp dirs, and not making outbound network calls at runtime. The SKILL.md does not instruct the agent to read unrelated system files or secret env vars.

Install Mechanism

Install is via npm/npx (registry.npmjs.org) which is a known public registry — appropriate for a Node-based tool but carries supply-chain risk. The document explicitly recommends pinning, vendoring, or building from source to avoid runtime fetches and claims no postinstall hooks; these mitigations are provided but the verifier should confirm them before trusting automatic npx usage.

Credentials

No environment variables, credentials, or unrelated config paths are requested. Access is limited to files under the user's home directory and system temp dirs, which is proportionate for editing .docx files.

Persistence & Privilege

always:false (not force-included). The skill requires adding an MCP server entry to client config, which is normal and scoped to this connector. It does not request to modify other skills or system-wide settings.

Scan Findings in Context

[no_findings_instruction_only] expected: Regex scanner had nothing to analyze because this is an instruction-only skill that recommends an external npm package. Lack of findings is expected but does not verify the external package's contents.

Assessment

This skill appears coherent for local .docx editing, but the main risk is the one-time npm fetch (npx). Before using: (1) prefer a pinned or vendored installation or build-from-source as described in the SKILL.md; (2) inspect the referenced GitHub repo and package.json (confirm no postinstall hooks and verify the claimed stdio-only server); (3) run initial tests in an isolated environment to ensure no unexpected network activity; (4) confirm the MCP client configuration only gives the connector access to the intended home/temp paths. If you cannot audit the upstream package, avoid using npx auto-fetch and use the offline/pinned options provided.

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:

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)

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

# 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 <release-tag>
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:

• Change clauses or paragraphs in an existing .docx
• 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

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

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

Tag	Effect
<b>text</b>	Bold
<i>text</i>	Italic
<u>text</u>	Underline
<highlighting>text</highlighting>	Yellow highlight

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.

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)

Insert Paragraphs

insert_paragraph adds new content before or after an anchor paragraph.

• position: "BEFORE" or "AFTER" (default "AFTER")
• style_source_id: 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

format_layout 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: clawhub install open-agreements/open-agreements
• Outlook Email Management (outlook-email-management) — manage Outlook email with AI agents: clawhub install stevenobiajulu/outlook-email-management

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: clawhub star usejunior/docx-editing