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 von UseJunior — nutzen Sie Coding-Agents auch für den Papierkram.

Teil der UseJunior Entwickler-Tools.

Safe Docx ist ein Open-Source-TypeScript-Stack für die chirurgische Bearbeitung bestehender Microsoft Word .docx-Dateien. Er wurde für Workflows entwickelt, bei denen ein Agent Änderungen vorschlägt und ein Mensch dennoch zuverlässige, formatierungserhaltende Dokumentenänderungen benötigt.

Wenn Sie Verträge mit KI prüfen, ist der langsamste Schritt oft das Anwenden akzeptierter Empfehlungen in Word. Safe Docx verwandelt dies in deterministische Tool-Aufrufe.

Warum gibt es das?

KI-Coding-CLIs sind großartig bei Code- und Textdateien, aber schwach bei der Bearbeitung von bestehenden .docx-Dateien. Geschäfts- und Rechtsabläufe basieren immer noch auf Word-Dokumenten, daher haben wir einen nativen TypeScript-Pfad entwickelt für:

  • das Lesen und Durchsuchen bestehender Dokumente in token-effizienten Formaten

  • chirurgische Änderungen, ohne die Formatierung zu zerstören

  • die Erstellung sauberer/nachverfolgbarer Ausgaben und Artefakte zur Revisions-Extraktion

Mission: Coding-Agents ermöglichen, auch Papierkram zu erledigen. Safe Docx konzentriert sich auf deterministische Änderungen an bestehenden Word-Dateien, bei denen Formatierung und Prüfungssemantik die Automatisierung überstehen müssen.

Related MCP server: docx-mcp

Positionierung

Safe Docx ist für Agenten-Workflows optimiert, die deterministische, lokale Änderungen an bestehenden .docx-Dateien erfordern:

  • typisierte MCP-Tools für Bearbeitung, Vergleich, Revisions-Extraktion, Kommentare, Fußnoten und Layout

  • prüfbares Verhalten mit Testnachweisen und Rückverfolgbarkeitsartefakten

  • TypeScript-Laufzeitverteilung, ohne dass Python oder LibreOffice für die unterstützte Nutzung erforderlich sind

Safe Docx ist nicht dazu gedacht, Bibliotheken zur Neuerstellung von .docx-Dateien zu ersetzen.

Vertraut von

  • Am Law Top-10-Kanzlei — mehrstufige Vertragstranslations-Pipeline

  • Regionale Kanzlei mit 150 Anwälten — über 22 Mio. Token an Vertrags-Markup verarbeitet

  • Gemini CLI — kompatible Word-Bearbeitungs-MCP-Erweiterung

Hier starten

npx -y @usejunior/safe-docx

Für eine detaillierte Einrichtung und Tool-Referenz siehe packages/docx-mcp/README.md.

Beispiel: Agent bearbeitet einen Vertrag

Wenn Sie einen Coding-Agent (Claude Code, Cursor, Gemini CLI) mit installiertem Safe Docx auffordern, führt der Agent MCP-Tool-Aufrufe wie diese aus:

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

Der Agent übernimmt die Tool-Aufrufe automatisch. Sie erhalten eine saubere Datei und eine Datei mit nachverfolgten Änderungen für die menschliche Überprüfung.

MCP-Schnellstart

Claude Code

claude mcp add safe-docx -- npx -y @usejunior/safe-docx

Claude Desktop

Hinzufügen zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %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"]
    }
  }
}

Jeder MCP-Client

  • Befehl: npx

  • Argumente: ["-y", "@usejunior/safe-docx"]

  • Transport: stdio

Wofür Safe Docx optimiert ist

  • Bearbeitung bestehender .docx-Dateien

  • Formatierungserhaltender Textersatz und Absatzeinfügung

  • Kommentar- und Fußnoten-Workflows

  • Ausgaben mit nachverfolgten Änderungen zur Überprüfung (download, compare_documents)

  • Revisions-Extraktion als strukturiertes JSON (extract_revisions)

Wofür Safe Docx nicht optimiert ist

Safe Docx ist kein Toolkit zur Neuerstellung von Dokumenten.

Wenn Ihr Hauptbedarf in der Generierung neuer .docx-Dateien aus Vorlagen/programmatischem Layout besteht, verwenden Sie Pakete wie docx.

Die lokale Safe Docx-Laufzeitumgebung lehnt derzeit auch absichtlich Word-Vorlagendateien (.dotx) ab. Konvertieren Sie die Vorlage in ein normales .docx-Dokument, bevor Sie es hier öffnen.

Dokumentenfamilien

Automatisierte Fixture-Abdeckung in diesem Repo

  • Common Paper-Stil gegenseitige NDA-Fixtures

  • Bonterms gegenseitige NDA-Fixture

  • Absichtserklärung-Fixture (Letter of Intent)

  • ILPA Limited Partnership Agreement Redline-Fixtures

Entwickelt für komplexe rechtliche und geschäftliche .docx-Klassen

  • NVCA-Finanzierungsformulare

  • YC SAFEs

  • Angebotsmemoranden

  • Bestellformulare und Dienstleistungsverträge

  • Limited Partnership Agreements

Pakete

  • @usejunior/docx-core: Primitive + Vergleichs-Engine für bestehende .docx-Dokumente

  • @usejunior/docx-mcp: MCP-Server-Implementierung und Tool-Oberfläche

  • @usejunior/safe-docx: Kanonischer Installationsname für Endbenutzer (npx -y @usejunior/safe-docx)

  • @usejunior/safedocx-mcpb: Privater MCP-Bundle-Wrapper

Zuverlässigkeit und Vertrauensbasis

  • Tool-Schemata werden aus packages/docx-mcp/src/tool_catalog.ts generiert.

  • OpenSpec-Rückverfolgbarkeitsmatrix: packages/docx-mcp/src/testing/SAFE_DOCX_OPENSPEC_TRACEABILITY.md

  • Annahmenmatrix: packages/docx-mcp/assumptions.md

  • Konformitätsleitfaden: docs/safe-docx/sprint-3-conformance.md

FAQ

Was ist Safe Docx?

Ein TypeScript-First DOCX-Bearbeitungs-Stack für Coding-Agent-Workflows, die deterministische, formatierungserhaltende Änderungen an bestehenden Word-Dokumenten benötigen.

Bleibt die Formatierung bei Änderungen erhalten?

Das ist ein zentrales Designziel. Die Tool-Oberfläche basiert auf chirurgischen Operationen (replace_text, insert_paragraph, Layout-Steuerungen), die die Dokumentenstruktur und Formatierungssemantik so weit wie möglich bewahren.

Erfordert dies .NET, Python oder LibreOffice im normalen Laufzeitbetrieb?

Nein. Die unterstützte Laufzeitnutzung ist JavaScript/TypeScript mit jszip + @xmldom/xmldom.

Kann dies Verträge von Grund auf neu generieren?

Nicht der primäre Fokus. Für die Neuerstellung verwenden Sie Pakete wie docx.

Auf welchen Dokumenttypen wurde dies in Repo-Fixtures getestet?

Gegenseitige NDAs (einschließlich Common Paper/Bonterms-Stil-Fixtures), Absichtserklärungen und ILPA Limited Partnership Agreement Redline-Fixtures.

Ist dies nur für Anwälte?

Nein. Die gleichen Probleme bei der Bearbeitung bestehender .docx-Dateien treten auch in den Bereichen Personalwesen, Beschaffung, Finanzen, Vertriebsbetrieb und anderen papierlastigen Workflows auf.

Wo sollte ich als MCP-Benutzer anfangen?

Verwenden Sie @usejunior/safe-docx via npx und folgen Sie dann den Einrichtungsbeispielen in packages/docx-mcp/README.md.

Wo kann ich die Tool-Schemata einsehen?

Siehe die generierte Referenz unter packages/docx-mcp/docs/tool-reference.generated.md.

Entwicklung

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

Siehe auch

Datenschutz

Safe Docx läuft vollständig auf Ihrem lokalen Computer. Es werden keine Dokumentinhalte an externe Server gesendet. Details finden Sie in unserer Datenschutzrichtlinie.

Governance

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