Safe Docx
Safe DOCX Suite
English | Español | 简体中文 | Português (Brasil) | Deutsch
safe-docx by UseJunior — use coding agents for paperwork too.
Part of the UseJunior developer tools.
Safe Docx is an open-source TypeScript stack for surgical editing of existing Microsoft Word .docx files. It is built for workflows where an agent proposes changes and a human still needs reliable, formatting-preserving document edits.
If you review contracts with AI, the slowest step is often applying accepted recommendations in Word. Safe Docx turns that into deterministic tool calls.
Why This Exists
AI coding CLIs are great with code and text files but weak on brownfield .docx editing. Business and legal workflows still run on Word documents, so we built a native TypeScript path for:
- reading and searching existing documents in token-efficient formats
- making surgical edits without destroying formatting
- producing clean/tracked outputs and revision extraction artifacts
Mission: enable coding agents to do paperwork too. Safe Docx focuses on deterministic edits to existing Word files where formatting and review semantics must survive automation.
Positioning
Safe Docx is optimized for agent workflows that need deterministic, local-first edits on existing .docx files:
- typed MCP tools for edit, compare, revision extraction, comments, footnotes, and layout
- auditable behavior with test evidence and traceability artifacts
- TypeScript runtime distribution without requiring Python or LibreOffice for supported usage
Safe Docx is not intended to replace generation-first .docx libraries.
Trusted By
- Am Law top-10 firm — multistep contract translation pipeline
- 150-lawyer regional firm — 22M+ tokens of contract markup processed
- Gemini CLI — compatible Word editing MCP extension
Start Here
npx -y @usejunior/safe-docx
For detailed setup and tool reference, see packages/docx-mcp/README.md.
Example: Agent Editing a Contract
When you prompt a coding agent (Claude Code, Cursor, Gemini CLI) with Safe Docx installed, the agent makes MCP tool calls like these:
User: Edit the NDA at ~/docs/NDA.docx — change the governing law
from "State of New York" to "State of Delaware" and save both
a clean copy and a tracked-changes copy.
Agent calls:
1. read_file(file_path="~/docs/NDA.docx", format="toon")
→ Returns paragraphs with stable IDs: _bk_1, _bk_2, ...
2. grep(file_path="~/docs/NDA.docx", pattern="State of New York")
→ Match in paragraph _bk_47
3. replace_text(
file_path="~/docs/NDA.docx",
target_paragraph_id="_bk_47",
old_string="State of New York",
new_string="State of Delaware",
instruction="Change governing law to Delaware"
)
4. save(
file_path="~/docs/NDA.docx",
save_to_local_path="~/docs/NDA-clean.docx",
tracked_save_to_local_path="~/docs/NDA-tracked.docx",
save_format="both"
)
The agent handles the tool calls automatically. You get a clean file and a tracked-changes file for human review.
MCP Quickstart
Claude Code
claude mcp add safe-docx -- npx -y @usejunior/safe-docx
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"safe-docx": {
"command": "npx",
"args": ["-y", "@usejunior/safe-docx"]
}
}
}
Gemini CLI
{
"mcpServers": {
"safe-docx": {
"command": "npx",
"args": ["-y", "@usejunior/safe-docx"]
}
}
}
Any MCP Client
- Command:
npx - Args:
["-y", "@usejunior/safe-docx"] - Transport: stdio
What Safe Docx Is Optimized For
- Brownfield editing of existing
.docxfiles - Formatting-preserving text replacement and paragraph insertion
- Comment and footnote workflows
- Tracked-changes outputs for review (
download,compare_documents) - Revision extraction as structured JSON (
extract_revisions)
What Safe Docx Is Not Optimized For
Safe Docx is not a from-scratch document generation toolkit.
If your primary need is generating new .docx files from templates/programmatic layout, use packages such as docx.
The local Safe Docx runtime also intentionally rejects Word template files (.dotx) for now. Convert the template to a normal .docx document before opening it here.
Document Families
Automated fixture coverage in this repo
- Common Paper style mutual NDA fixtures
- Bonterms mutual NDA fixture
- Letter of Intent fixture
- ILPA limited partnership agreement redline fixtures
Designed for complex legal and business .docx classes
- NVCA financing forms
- YC SAFEs
- Offering memoranda
- Order forms and services agreements
- Limited partnership agreements
Packages
@usejunior/docx-core: primitives + comparison engine for existing.docxdocuments@usejunior/docx-mcp: MCP server implementation and tool surface@usejunior/safe-docx: canonical end-user install name (npx -y @usejunior/safe-docx)@usejunior/safedocx-mcpb: private MCP bundle wrapper
Reliability and Trust Surface
- Tool schemas are generated from
packages/docx-mcp/src/tool_catalog.ts. - OpenSpec traceability matrix:
packages/docx-mcp/src/testing/SAFE_DOCX_OPENSPEC_TRACEABILITY.md - Assumption matrix:
packages/docx-mcp/assumptions.md - Conformance guide:
docs/safe-docx/sprint-3-conformance.md
FAQ
What is Safe Docx?
A TypeScript-first DOCX editing stack for coding-agent workflows that need deterministic, formatting-preserving edits on existing Word documents.
Does this preserve formatting during edits?
That is a core design goal. The tool surface is built around surgical operations (replace_text, insert_paragraph, layout controls) that preserve document structure and formatting semantics as much as possible.
Does this require .NET, Python, or LibreOffice in normal runtime usage?
No. Supported runtime usage is JavaScript/TypeScript with jszip + @xmldom/xmldom.
Can this generate contracts from scratch?
Not the primary focus. For from-scratch generation, use packages such as docx.
What document types has this been tested on in-repo fixtures?
Mutual NDAs (including Common Paper/Bonterms-style fixtures), Letter of Intent, and ILPA limited partnership agreement redline fixtures.
Is this only for lawyers?
No. The same brownfield .docx editing problems appear in HR, procurement, finance, sales ops, and other paperwork-heavy workflows.
Where should I start as an MCP user?
Use @usejunior/safe-docx via npx, then follow setup examples in packages/docx-mcp/README.md.
Where can I inspect the tool schemas?
See the generated reference at packages/docx-mcp/docs/tool-reference.generated.md.
Development
npm ci
npm run build
npm run lint --workspaces --if-present
npm run test:run
npm run check:spec-coverage
npm run test:coverage:packages
npm run coverage:packages:check
npm run coverage:matrix
See Also
- Open Agreements — fill standard legal templates with coding agents (NDAs, SAFEs, NVCA)
- UseJunior Developer Tools — product page with install options and tool catalog
Privacy
Safe Docx runs entirely on your local machine. No document content is sent to external servers. See our Privacy Policy for details.
Governance
Server Config
{
"mcpServers": {
"safe-docx": {
"command": "npx",
"args": [
"-y",
"@usejunior/safe-docx"
]
}
}
}