Skip to main content
Glama

Safe DOCX Suite

CI codecov npm version License: MIT GitHub last commit GitHub issues closed

English | Español | 简体中文 | Português (Brasil | Deutsch

safe-docx by UseJunior — コーディングエージェントを事務作業にも活用しましょう。

UseJunior 開発者ツールの一部です。

Safe Docxは、既存のMicrosoft Word .docxファイルを外科的に編集するためのオープンソースのTypeScriptスタックです。エージェントが変更を提案し、人間が信頼性の高い書式保持型の文書編集を行う必要があるワークフロー向けに構築されています。

AIで契約書をレビューする場合、最も時間がかかるのは、承認された推奨事項をWordに適用する作業です。Safe Docxは、それを決定論的なツール呼び出しに変換します。

なぜこれが存在するのか

AIコーディングCLIはコードやテキストファイルには優れていますが、既存の.docx編集には弱いです。ビジネスや法務のワークフローは依然としてWord文書で動いているため、私たちは以下のためのネイティブなTypeScriptパスを構築しました。

  • トークン効率の良い形式で既存の文書を読み込み、検索する

  • 書式を壊さずに外科的な編集を行う

  • クリーンな出力や変更履歴付きの出力、リビジョン抽出アーティファクトを生成する

ミッション:コーディングエージェントが事務作業もできるようにすること。Safe Docxは、自動化後も書式やレビューのセマンティクスを維持する必要がある、既存のWordファイルへの決定論的な編集に焦点を当てています。

Related MCP server: docx-mcp

ポジショニング

Safe Docxは、既存の.docxファイルに対して決定論的でローカルファーストな編集を必要とするエージェントワークフロー向けに最適化されています。

  • 編集、比較、リビジョン抽出、コメント、脚注、レイアウトのための型定義されたMCPツール

  • テストエビデンスとトレーサビリティアーティファクトによる監査可能な動作

  • PythonやLibreOfficeを必要としないTypeScriptランタイム配布

Safe Docxは、生成ファーストの.docxライブラリを置き換えることを意図したものではありません。

導入実績

  • Am Lawトップ10法律事務所 — 多段階の契約書翻訳パイプライン

  • 弁護士150名規模の地域事務所 — 2200万トークン以上の契約書マークアップを処理

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

Claude 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文書に変換してから開いてください。

文書ファミリー

このリポジトリ内の自動フィクスチャカバレッジ

  • Common Paperスタイルの相互NDAフィクスチャ

  • Bontermsの相互NDAフィクスチャ

  • 意向表明書(LOI)フィクスチャ

  • 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とは何ですか?

既存のWord文書に対して、決定論的かつ書式を保持した編集を必要とするコーディングエージェントワークフローのための、TypeScriptファーストのDOCX編集スタックです。

編集中に書式は保持されますか?

それが設計の核心です。ツールインターフェースは、文書構造と書式のセマンティクスを可能な限り保持する外科的な操作(replace_text、insert_paragraph、レイアウト制御)を中心に構築されています。

通常のランタイム使用で.NET、Python、LibreOfficeが必要ですか?

いいえ。サポートされているランタイム使用は、jszip + @xmldom/xmldom を使用したJavaScript/TypeScriptです。

ゼロから契約書を生成できますか?

主な目的ではありません。ゼロからの生成には、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 Developer Tools — インストールオプションとツールカタログを備えた製品ページ

プライバシー

Safe Docxは完全にローカルマシン上で実行されます。文書の内容が外部サーバーに送信されることはありません。詳細はプライバシーポリシーを参照してください。

ガバナンス

Available Tools

30 tools
accept_ai_editsA
Destructive

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

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

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

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

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

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

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_documentsA
Read-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_commentA
Destructive

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

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_revisionsA
Read-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_layoutA
Destructive

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

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

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_commentsA
Read-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_outlineA
Read-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_statusA
Read-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_footnotesA
Read-only

Get all footnotes from the document with IDs, display numbers, text, and anchored paragraph IDs. Read-only.

Inputs: file_path (required).

get_sectionsA
Read-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.

grepA
Read-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_changesA
Read-only

Check whether the document body contains tracked-change markers (insertions, deletions, moves, and property-change records). Read-only.

Inputs: file_path (required).

insert_paragraphA
Destructive

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

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_fileA
Read-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_editsA
Destructive

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

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.

saveA
Destructive

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

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

    A3.7/5.0

    Scored across 30 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

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

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers