safe-docx
Safe DOCX 套件
English | Español | 简体中文 | Português (Brasil) | Deutsch
safe-docx 由 UseJunior 提供 — 让编程智能体也能处理文书工作。
属于 UseJunior 开发者工具 系列。
Safe Docx 是一个开源的 TypeScript 技术栈,用于对现有的 Microsoft Word .docx 文件进行精细化编辑。它专为智能体提出修改建议、而人类仍需进行可靠且保留格式的文档编辑的工作流而构建。
如果您使用 AI 审阅合同,最耗时的步骤通常是在 Word 中应用已接受的建议。Safe Docx 将其转化为确定性的工具调用。
为什么存在这个项目
AI 编程 CLI 在处理代码和文本文件方面表现出色,但在处理现有的 .docx 编辑时却很薄弱。商业和法律工作流仍然依赖 Word 文档,因此我们构建了一个原生的 TypeScript 路径,用于:
以 token 高效的格式读取和搜索现有文档
进行精细化编辑而不破坏格式
生成干净/带修订记录的输出和修订提取工件
使命:让编程智能体也能处理文书工作。Safe Docx 专注于对现有 Word 文件进行确定性编辑,确保格式和审阅语义在自动化过程中得以保留。
Related MCP server: docx-mcp
定位
Safe Docx 针对需要对现有 .docx 文件进行确定性、本地优先编辑的智能体工作流进行了优化:
用于编辑、对比、修订提取、批注、脚注和布局的类型化 MCP 工具
具有测试证据和可追溯性工件的可审计行为
TypeScript 运行时分发,在支持的使用场景下无需 Python 或 LibreOffice
Safe Docx 不旨在取代生成优先的 .docx 库。
受信任方
Am Law 前 10 强律所 — 多步骤合同翻译流水线
150 名律师的区域性律所 — 处理了超过 2200 万 token 的合同标记
Gemini CLI — 兼容的 Word 编辑 MCP 扩展
从这里开始
npx -y @usejunior/safe-docx有关详细设置和工具参考,请参阅 packages/docx-mcp/README.md。
示例:智能体编辑合同
当您在安装了 Safe Docx 的情况下提示编程智能体(Claude Code、Cursor、Gemini CLI)时,智能体会进行如下 MCP 工具调用:
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"
)智能体会自动处理工具调用。您将获得一个干净的文件和一个供人工审阅的修订记录文件。
MCP 快速入门
Claude Code
claude mcp add safe-docx -- npx -y @usejunior/safe-docxClaude Desktop
添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %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"]
}
}
}任何 MCP 客户端
命令:
npx参数:
["-y", "@usejunior/safe-docx"]传输: stdio
Safe Docx 的优化方向
对现有
.docx文件的存量编辑保留格式的文本替换和段落插入
批注和脚注工作流
用于审阅的修订记录输出 (
download,compare_documents)作为结构化 JSON 的修订提取 (
extract_revisions)
Safe Docx 不优化的方向
Safe Docx 不是一个从零开始的文档生成工具包。
如果您的主要需求是从模板/程序化布局生成新的 .docx 文件,请使用诸如 docx 之类的包。
目前的本地 Safe Docx 运行时也暂时有意拒绝 Word 模板文件 (.dotx)。请在打开之前将模板转换为普通的 .docx 文档。
文档系列
本仓库中的自动化测试覆盖
通用纸张风格的互惠 NDA 测试
Bonterms 互惠 NDA 测试
意向书测试
ILPA 有限合伙协议修订测试
专为复杂的法律和商业 .docx 类设计
NVCA 融资表格
YC SAFE
发行备忘录
订单表格和服务协议
有限合伙协议
包
@usejunior/docx-core:现有.docx文档的原语 + 对比引擎@usejunior/docx-mcp:MCP 服务器实现和工具界面@usejunior/safe-docx:规范的最终用户安装名称 (npx -y @usejunior/safe-docx)@usejunior/safedocx-mcpb:私有 MCP 包封装
可靠性和信任面
工具模式由
packages/docx-mcp/src/tool_catalog.ts生成。OpenSpec 可追溯性矩阵:
packages/docx-mcp/src/testing/SAFE_DOCX_OPENSPEC_TRACEABILITY.md假设矩阵:
packages/docx-mcp/assumptions.md一致性指南:
docs/safe-docx/sprint-3-conformance.md
常见问题解答
什么是 Safe Docx?
一个以 TypeScript 为先的 DOCX 编辑栈,适用于需要对现有 Word 文档进行确定性、保留格式编辑的编程智能体工作流。
这在编辑过程中能保留格式吗?
这是核心设计目标。工具界面围绕精细化操作(replace_text、insert_paragraph、布局控制)构建,尽可能保留文档结构和格式语义。
在正常运行时需要 .NET、Python 或 LibreOffice 吗?
不需要。支持的运行时使用 JavaScript/TypeScript 配合 jszip + @xmldom/xmldom。
这能从零开始生成合同吗?
不是主要重点。对于从零开始的生成,请使用诸如 docx 之类的包。
这在仓库内测试中测试过哪些文档类型?
互惠 NDA(包括 Common Paper/Bonterms 风格的测试)、意向书和 ILPA 有限合伙协议修订测试。
这只适用于律师吗?
不是。同样的问题也出现在人力资源、采购、财务、销售运营和其他文书工作繁重的工作流中。
作为 MCP 用户,我应该从哪里开始?
通过 npx 使用 @usejunior/safe-docx,然后按照 packages/docx-mcp/README.md 中的设置示例进行操作。
我在哪里可以查看工具模式?
请参阅 packages/docx-mcp/docs/tool-reference.generated.md 中的生成参考。
开发
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另请参阅
Open Agreements — 使用编程智能体填充标准法律模板(NDA、SAFE、NVCA)
UseJunior 开发者工具 — 包含安装选项和工具目录的产品页面
隐私
Safe Docx 完全在您的本地机器上运行。不会将任何文档内容发送到外部服务器。详情请参阅我们的 隐私政策。
治理
Available Tools
30 toolsaccept_ai_editsADestructive
Selectively accept tracked changes by revision id or author in the in-memory session, leaving all other (e.g. third-party reviewer) revisions byte-untouched. This does not write file_path; call save to persist the mutation. Provide revision_ids (array of w:id values) to target specific revisions, or author to accept every revision by one actor. Sweeps document.xml and supported side-story parts (footnotes, endnotes, comments). An ambiguous overlap — a targeted revision structurally containing, or contained by, a non-targeted revision (nested ins/del/move) — hard-errors with code AMBIGUOUS_REVISION_OVERLAP and a structured overlaps list unless normalize_first is set (best-effort, no byte-identical promise).
Inputs: file_path (required), author, revision_ids, normalize_first.
accept_changesBDestructive
Accept every supported tracked change in the document body, including inserted and deleted table-row revisions. Returns acceptance stats; unresolvedRowRevisions remains 0 for supported row markers.
Inputs: file_path (required).
add_commentADestructive
Add a comment or threaded reply to a document. Provide target_paragraph_id + anchor_text for root comments, or parent_comment_id for replies. Supports DOCX and ODT (ODT backs comments with office:annotation; threaded replies are DOCX-only). Surface: revisionable + package-mutation — the body-story comment reference is tracked (w:ins), while comment text and author metadata are recorded in the save report non-revision change manifest.
Inputs: text (required), author (required), file_path (required), initials, +3 more.
add_footnoteADestructive
Add a footnote anchored to a paragraph. Optionally position the reference after specific text using after_text. Note: [^N] markers in read_file output are display-only and not part of the editable text used by replace_text. Surface: revisionable + package-mutation — the footnote reference and note text are tracked (w:ins), while footnote-part creation and registration are recorded in the save report non-revision change manifest.
Inputs: text (required), file_path (required), target_paragraph_id (required), after_text.
batch_editADestructive
Single-agent front door for applying multiple edit steps (replace_text, insert_paragraph) to a document in one call. Validates all steps first, rejects conflicts before applying anything, then executes valid steps sequentially. Two source-proven bonded heading/body insertions may share an anchor and position when both declare the same bonded_pair_id and distinct style_source_id values; unrelated same-slot inserts remain conflicts. Accepts inline steps or a plan_file_path JSON array. Surface: revisionable — every applied step emits native OOXML tracked changes.
Inputs: file_path (required), steps, plan_file_path.
clear_formattingADestructive
Clear specific run-level formatting (bold, italic, underline, highlight, color, font) from paragraphs. Surface: revisionable — clearing emits a native run-property-change revision (w:rPrChange).
Inputs: file_path (required), clear_bold, clear_font, clear_color, +4 more.
close_fileADestructive
Close an open file session, or close all sessions with explicit confirmation. Supports DOCX, ODT, and Google Docs.
Inputs: confirm, clear_all, file_path, google_doc_id.
compare_documentsARead-only
Compare two documents and produce a tracked-changes output document. Provide original_file_path + revised_file_path for standalone comparison, or file_path to compare session edits against the original. DOCX and ODF (.odt) support both modes. DOCX output always uses the revised archive as its package base and publishes tagged revisions; engine, strategy, reconstruction, premerge, and refinement selectors are not exposed. DOCX stats count insertions/deletions as contiguous ranges, expose tagged-token-v1 totals as insertedAtoms/deletedAtoms with atomMetricVersion, report formatChanges separately from modifiedParagraphs, and report detected moves as moves/movedParagraphs with moveFromRanges/moveToRanges (moved content is not also counted as insertions or deletions, so a pure move reports moves > 0 with zero insertions/deletions). When a DOCX input difference is preserved in the output without tracked-change markup (for example a removed section's header or footer, or an unsupported header/footer topology), the response includes unrepresented_changes (objects with scope, kind, sectionIndex, for header/footer scopes role, and for the contentControl scope a contentControl identity: a changed w:sdtPr/w:sdtEndPr is published as the revised properties without markup, because CT_SdtPr admits no revision elements) plus one warnings string per entry, and the message carries a WARNING. Both fields are absent when no reportable unrepresented change was detected; the detector covers section properties, selected header/footer stories and content-control properties, so absence is not a guarantee about differences outside that scope. ODF compares at inline granularity (a modified paragraph is marked up in place — only the changed spans are struck or inserted).
Inputs: save_to_local_path (required), author, file_path, compare_moves, +4 more.
convert_to_odtA
Convert a DOCX document to OpenDocument Text (.odt) using the native model-to-model converter (no LibreOffice involved). Writes the .odt (default: source path with the .odt extension), validates ODF packaging safety before writing, and returns the output path plus a lossiness summary itemizing every downgraded construct. Conversion is semantic and intentionally lossy: text, headings, bold/italic/underline, hyperlinks, lists, and tables are mapped; richer styling, tracked changes, comments, and headers/footers are not. DOCX in, ODT out — Google Docs and .odt inputs are not supported.
Inputs: file_path, output_path, allow_overwrite.
delete_commentADestructive
Delete a comment and all its threaded replies from the document. Cascade-deletes all descendants. Surface: revisionable + package-mutation — the body-story comment reference removal is tracked (w:del), while comment/reply text cleanup is recorded in the save report non-revision change manifest.
Inputs: file_path (required), comment_id (required).
delete_footnoteADestructive
Delete a footnote and its reference from the document. Surface: revisionable — the reference and note text are removed as native OOXML tracked deletions (w:del).
Inputs: note_id (required), file_path (required).
exportA
Export a document to a portable rendering (Markdown, semantic HTML, or plain text). Writes an output file (default: source path with the format extension, e.g. .md, .html, or .txt) and returns its path, byte count, and the rendered content (under content). Intentionally lossy (no round-trip); HTML is the semantic tier, not pixel-faithful. DOCX only — Google Docs is not supported.
Inputs: format, file_path, output_path, allow_overwrite, +1 more.
extract_revisionsARead-only
Extract tracked changes as structured JSON with before/after text per paragraph, revision details, and comments. Table rows inserted or deleted as a whole, and row property changes (w:trPr > w:ins / w:del / w:trPrChange), are reported as records with scope "row", keyed by the row's first paragraph, whose revisions are ROW_INSERTION / ROW_DELETION / FORMAT_CHANGE entries carrying the revision id, author and date. Supports pagination via offset and limit. Read-only - does not modify the document.
Inputs: file_path (required), limit, offset.
format_layoutADestructive
Apply layout controls (paragraph spacing, paragraph alignment and pagination flags, table row height, cell padding). paragraph_properties sets alignment (w:jc) and sets (true) or removes (false) direct pageBreakBefore/keepNext/keepLines; requests that change nothing are no-ops. Google Docs supports paragraph spacing only. Surface: revisionable — DOCX geometry edits emit native property-change revisions (w:pPrChange/w:trPrChange/w:tcPrChange).
Inputs: strict, file_path, row_height, cell_padding, +3 more.
format_numberingADestructive
Change one DOCX body paragraph’s direct numbering reference. Use remove=true to drop direct w:numPr, match_paragraph_id to adopt another paragraph’s explicit numbering, or num_id with ilvl to reference an existing numbering definition. This tool does not create numbering definitions or change style-inherited numbering. Effective edits emit a native w:pPrChange; identical requests are no-ops.
Inputs: target_paragraph_id (required), ilvl, num_id, remove, +3 more.
format_sectionADestructive
Partially update one DOCX section’s page-number restart, page dimensions/orientation, or margins using a zero-based section_index from get_sections. Effective calls emit one native w:sectPrChange and preserve section topology, page-number format, columns, break type, and header/footer references. Orientation is literal and does not automatically swap dimensions. This tool does not create sections or edit header/footer content.
Inputs: section_index (required), margins, file_path, page_size, +2 more.
get_commentsARead-only
Get all comments from the document with IDs, authors, dates, text, and anchored paragraph IDs. Range-anchored DOCX comments also expose optional end_paragraph_id, start_run_index, start_char_offset, end_run_index, and end_char_offset fields describing the covered span. Includes threaded replies (DOCX). Supports DOCX and ODT. Read-only.
Inputs: file_path (required).
get_document_outlineARead-only
Get a compact structural map of a document's headings (DOCX only). Each entry is {paragraph_id, text, level, source}, plus list_label (e.g. "Section 1.01") when the heading is numbered; Markdown puts the label before the text. Deterministic sources are word_style, list_metadata, and outline_level, selected in that precedence order and included by default. Heuristic sources are run_in_header, title_with_period, title_with_colon, title_caps_centered, and title_bare; set include_heuristic_headings=true to include them. JSON preserves levels 1-9; Markdown clamps visual ATX depth to 6. Read-only.
Inputs: format, file_path, include_heuristic_headings.
get_file_statusARead-only
Get file/session metadata including edit count, normalization stats, and cache info. Supports DOCX, ODT, and Google Docs.
Inputs: file_path, google_doc_id.
get_footnotesARead-only
Get all footnotes from the document with IDs, display numbers, text, and anchored paragraph IDs. Read-only.
Inputs: file_path (required).
get_sectionsARead-only
Read DOCX main-document sections in document order. Returns zero-based session-relative section_index values, paragraph/body boundary metadata, page numbering, page size, margins, and header/footer relationship references. Call again after any operation that changes section topology. Read-only.
Inputs: file_path, google_doc_id.
grepARead-only
Search paragraphs with regex. Use file_path for session-based search, file_paths for stateless multi-file search, or google_doc_id for Google Docs. ODT supported via file_path (single-file) only.
Inputs: pattern, patterns, file_path, file_paths, +8 more.
has_tracked_changesARead-only
Check whether the document body contains tracked-change markers (insertions, deletions, moves, and property-change records). Read-only.
Inputs: file_path (required).
insert_paragraphADestructive
Insert a paragraph before/after an anchor paragraph by paragraph id. DOCX responses include structural_warnings when the placement may slice a hierarchy, mismatch list levels, or renumber a list. Supports DOCX, ODT, and Google Docs. ODT paragraph ids remain stable within the session; new paragraphs receive monotonically allocated ids, and reopening renumbers stored document order. Surface: revisionable — DOCX insertions emit native OOXML tracked changes.
Inputs: new_string (required), instruction (required), positional_anchor_node_id (required), position, +3 more.
insert_section_breakADestructive
Insert a tracked DOCX section break after a stable direct-body paragraph. The new boundary preserves the containing section’s page setup and header/footer relationship references. The following section inherits current properties by default; set inherit_properties=false to reset non-relationship properties, and optionally provide page-number/page-size/margin overrides in new_section. Call get_sections again after success because section indexes change.
Inputs: break_type (required), paragraph_id (required), file_path, new_section, +1 more.
read_fileARead-only
Read document content (DOCX, ODT, or Google Doc). Output is token-limited (~14k tokens) by default with pagination metadata (has_more, next_offset). Use offset/limit to paginate.
Inputs: limit, format, offset, node_ids, +7 more.
reject_ai_editsADestructive
Selectively reject tracked changes by revision id or author in the in-memory session (restoring their pre-edit state), leaving all other revisions byte-untouched. This does not write file_path; call save to persist the mutation. Symmetric to accept_ai_edits: provide revision_ids or author, sweeps document.xml and supported side-story parts, and hard-errors on an ambiguous overlap (code AMBIGUOUS_REVISION_OVERLAP with a structured overlaps list) unless normalize_first is set.
Inputs: file_path (required), author, revision_ids, normalize_first.
replace_textADestructive
Replace text in a paragraph by provider paragraph id, preserving formatting where supported. Supports DOCX, ODT, and Google Docs. To delete an ordinary DOCX body paragraph, pass its complete visible text as old_string and an empty new_string; a clean save removes the paragraph and a tracked save keeps the deletion for review. Do not use this shortcut for paragraphs that carry section properties, are structurally required by a table cell, or own bookmark/comment anchors without inspecting the structure first. Surface: revisionable — DOCX edits emit native OOXML tracked changes (w:ins/w:del/w:rPrChange).
Inputs: new_string (required), old_string (required), instruction (required), target_paragraph_id (required), +3 more.
saveADestructive
Persist the current in-memory document session. For DOCX: saves clean and/or tracked changes output. For ODT: saves an .odt package. For Google Docs: checkpoint (default) returns revisionId, or snapshot exports as DOCX. Surface: revisionable — the save report lists both the AI revisions applied and a non-revision change manifest of any package-level mutations (comment/footnote side parts, relationships) that have no tracked-change wrapper.
Inputs: save_to_local_path (required), file_path, save_format, google_doc_id, +7 more.
update_footnoteADestructive
Update the text content of an existing footnote. Surface: revisionable — note-text changes emit native OOXML tracked changes (w:ins/w:del) inside the footnote body.
Inputs: note_id (required), new_text (required), file_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools target a distinct resource+action (comments, footnotes, sections, formatting, revisions), and descriptions clarify the boundaries. The main overlap is accept_changes vs accept_ai_edits/reject_ai_edits and batch_edit vs insert_paragraph/replace_text, where an agent must read carefully to pick the right one.
Names are uniformly snake_case and overwhelmingly verb-first (add_comment, get_sections, format_section, delete_footnote), with clear resource suffixes. Minor deviations are bare verbs (save, grep, export) and a get_/read_ split for retrieval tools (read_file vs get_file_status/get_comments).
At 30 tools this is heavy, though the domain (DOCX/ODT/Google Docs editing with tracked changes, comments, footnotes, sections, conversion) genuinely justifies breadth. Some consolidation is plausible — four format_* tools and three accept/reject revision tools could be grouped — so it sits at the borderline.
Coverage is broad: read/search/outline, edit (batch and single-step), save/export/convert, comments and footnotes CRUD, section and formatting edits, plus accept/reject and revision extraction. Gaps are modest: no reject-all counterpart to accept_changes, no comment text update, and no table or header/footer content editing.
Maintenance
Related MCP Connectors
Document editing, AI writing, saved documents, DOCX downloads, PDF, STT, TTS and watermarking
Convert DOCX documents to and from PDF, TXT, HTML, ODT, JPG and RTF.
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
PDF to Word that keeps the layout, merge, split, compress, OCR, PDF/A and more
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA powerful Word document processing service based on FastMCP, enabling AI assistants to create, edit, and manage docx files with full formatting support. Preserves original styles when editing content.193-
- AlicenseBqualityDmaintenanceEnables comprehensive management of Microsoft Word documents with 30+ tools for reading, writing, formatting, template merging, image extraction, equation extraction, and style application.241MIT
- AlicenseAqualityBmaintenanceFill standard legal agreement templates (NDAs, SAFEs, NVCA docs, employment, cloud terms) and produce DOCX files.35,330 npm66Apache 2.0
- AlicenseAqualityDmaintenanceProvides comprehensive read/write access to Word documents, including comments, track changes, and reply threads.91MIT