Metadata-Version: 2.4
Name: kitchensink4word
Version: 1.2.1
Summary: Everything and the kitchen sink for Microsoft Word - the most complete .docx MCP server: native citations/bibliography, index, tables with merge-aware column ops, footnotes/endnotes, TOC, tracked-change writing, document compare/merge, protection, watermarks, template transfer, safe round-trip OOXML editing
Author: Nykolus Alvut
License: # KitchenSink4Word
        
        Copyright (c) 2026 Nykolus Alvut
        
        Licensed under the PolyForm Noncommercial License 1.0.0 (below).
        Free for personal, academic, research, and other noncommercial use.
        **Commercial use requires a separate license — open a GitHub issue or
        contact the maintainer to arrange one.**
        
        ---
        
        # PolyForm Noncommercial License 1.0.0
        
        <https://polyformproject.org/licenses/noncommercial/1.0.0>
        
        ## Acceptance
        
        In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
        
        ## Copyright License
        
        The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
        
        ## Distribution License
        
        The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
        
        > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
        
        ## Changes and New Works License
        
        The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
        
        ## Patent License
        
        The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
        
        ## Noncommercial Purposes
        
        Any noncommercial purpose is a permitted purpose.
        
        ## Personal Uses
        
        Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
        
        ## Noncommercial Organizations
        
        Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
        
        ## Fair Use
        
        You may have "fair use" rights for the software under the law. These terms do not limit them.
        
        ## No Other Rights
        
        These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
        
        ## Patent Defense
        
        If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
        
        ## Violations
        
        The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
        
        ## No Liability
        
        ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
        
        ## Definitions
        
        The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
        
        **You** refers to the individual or entity agreeing to these terms.
        
        **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
        
        **Your licenses** are all the licenses granted to you for the software under these terms.
        
        **Use** means anything you do with the software requiring one of your licenses.
        
Keywords: mcp,word,docx,ooxml,claude,model-context-protocol
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp
Requires-Dist: python-docx
Requires-Dist: lxml
Requires-Dist: regex
Requires-Dist: pywin32; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Dynamic: license-file

<!-- mcp-name: io.github.nometalalchemist/kitchensink4word -->

# 🚰 KitchenSink4Word

**Everything and the kitchen sink for Microsoft Word.** The most complete
Word (.docx) MCP server available — 119 tools, corruption-proof by
construction, stress-tested against real dissertation manuscripts.

> **The origin story:** an AI agent once needed *fifteen minutes* to edit
> twenty table cells in a Word document, because no existing Word MCP could
> delete a table column, bulk-edit cells, manage footnotes, AND insert a TOC.
> So instead of installing three mediocre servers, this one got built in a
> day — and now your agents won't have that problem.

## Why this one (the honest comparison)

Every public Word MCP server was surveyed before building this (August 2026):

| Capability | KitchenSink4Word | GongRzhe Office-Word (2.1k★, archived) | word-mcp-live (195★) | SecurityRonin docx-mcp (43★) |
|---|---|---|---|---|
| Table column insert/delete | ✅ merge-aware | ❌ | ❌ | ❌ |
| Bulk cell edits (one call) | ✅ | ❌ | ❌ | ❌ |
| Cell merge/unmerge | ✅ | merge only | ❌ | ❌ |
| Footnotes AND endnotes CRUD | ✅ + conversion | add only | ❌ | ✅ |
| TOC insert + refresh | ✅ | ❌ | ❌ | ❌ |
| Native citations/bibliography | ✅ 12 styles | ❌ | ❌ | ❌ |
| Index generation | ✅ | ❌ | ❌ | ❌ |
| Tracked-change WRITING | ✅ | ❌ | ✅ | ✅ |
| Accept/reject by author | ✅ | ❌ | partial | ✅ |
| Document compare + combine | ✅ Word-native | ❌ | ❌ | buggy |
| Watermarks / protection / line numbers | ✅ | protect only | ❌ | ❌ |
| Section moving / template transfer | ✅ | ❌ | ❌ | ❌ |
| Atomic saves + auto-backup | ✅ | ❌ | ❌ | ❌ |

**119 tools** across: text and formatting, tables (including merge-aware column
insert/delete and one-call bulk cell edits), footnotes/endnotes (full CRUD +
footnote↔endnote conversion), TOC and caption lists, headers/footers/sections,
images, bulleted/numbered lists, threaded comments, tracked changes (read,
accept/reject by author, AND write edits as tracked changes), plus
Word-COM-backed document compare, field refresh, PDF export, and open-clean
validation on Windows.

## What's new in v1.2 (2026-08-28)

- **Word-native citations & bibliography**: structured source store, CITATION
  fields with page/suppress switches, BIBLIOGRAPHY field, 12 selectable styles
  (APA, Chicago, MLA, IEEE, ...) — verified end-to-end: Word renders the
  fields in the selected style.
- **Index** (XE entries with nesting and see-references + INDEX field) and
  **caption lists** (List of Tables/Figures).
- **Dissertation layout kit**: roman-numeral page formats, line numbering,
  watermarks (compatible with Word's Remove Watermark), multi-column
  sections, Page X of Y.
- **Document protection** with Word-compatible SHA-512 password hashing
  (verified byte-for-byte against Word's own output); the trackedChanges mode
  forces recipients' edits to be tracked.
- **Structure ops**: move_section (a heading plus its entire section, tables
  included), template transfer (restyle to match a reference document with
  name-based style remapping), custom styles, character styles, document
  properties, image alt text.
- **Table completions**: gridBefore/gridAfter rows, named table styles, sort,
  split, header-row repeat, nested-table read/write, cell text direction.
- **Formatting long-tail**: small caps, hidden text, character spacing,
  kerning, CJK language tagging, tab stops with leaders, paragraph
  borders/shading, widow control, change-case.
- **Analysis**: per-section word counts, APA citation-parity checking, Word's
  proofing errors and readability statistics, chapter merge, reviewer
  combine, password-encrypted saving.

## What makes it different

- **Merge-aware table column operations.** `delete_columns` / `insert_columns`
  work correctly through horizontally and vertically merged cells (gridSpan
  shrinks, vMerge chains re-root). At the time of writing, no other public
  Word MCP has this.
- **Bulk-first API.** Editing 20 cells is ONE `set_cells` call with a payload,
  not 20 round-trips.
- **Tracked-change writing.** `track=True, author="Jane"` on replace/insert/
  delete/cell tools produces real Word revisions the recipient can
  accept/reject — proven round-trip against the server's own revision engine.
- **Document compare.** `com_compare_documents` produces a Word-native redline
  between two versions of a document.
- **Never corrupts.** Atomic saves (temp file → structural validation →
  replace), automatic timestamped backups before every mutation, byte-identical
  passthrough of anything not being edited (equations, textboxes, content
  controls survive untouched), and clean typed errors — a file open in Word is
  refused with a message, not a hang.
- **Fragmented-run safe.** Find/replace works across Word's arbitrarily split
  runs while preserving per-character formatting, with a ReDoS timeout guard on
  user regex and an optional `max_replacements` blast-radius limit.

## Requirements

- Windows (COM tools require Microsoft Word installed; all other tools are
  pure file manipulation and work without Word)
- Python 3.12+ (developed on 3.14)

## Install

```
git clone https://github.com/nometalalchemist/KitchenSink4Word
cd KitchenSink4Word
python -m venv .venv
.venv\Scripts\pip install -e .
```

Register with Claude Code:

```
claude mcp add word -s user -- <absolute-path-to>\word-mcp\.venv\Scripts\word-mcp.exe
```

## Safety model

- Every mutating tool takes `file_path` and writes a `<name>.bak-<timestamp>.docx`
  beside it before the first change (`backup=False` to skip).
- Saves are atomic and validated; a failed operation leaves the original
  byte-identical.
- Deleting content that carries footnote references automatically removes the
  now-orphaned definitions; `validate_document` / `validate_notes` report
  integrity in both directions.
- Paragraph deletion refuses ranges that would cut a field (TOC, PAGEREF) in
  half or silently swallow a section break.

## Testing

335 tests. The full suite runs against a corpus of real-world documents
(dissertation chapters, a thesis with 171 footnotes, a manuscript with 126
tracked changes and reviewer comments) that is **private and not shipped** —
corpus-dependent tests skip cleanly with an explanation. See
`tests/conftest.py` for how to supply your own corpus. `tests/word_validator.py`
opens outputs in invisible Word and fails on any repair prompt — the definitive
corruption check.

Development history: built with Claude Code in a single day (2026-08-27),
tested through three rounds — unit gates per phase, an edge-case session
(89 calls), and two "insane mode" rounds through the raw MCP stdio transport (scale
torture, pathological merge topologies, Unicode/schema fuzzing, ReDoS,
Word-lock lifecycle, COM leak checks), and a dedicated cross-feature
interaction bug-hunt. All findings fixed with regression tests. `research/` documents the OOXML
algorithms and pitfalls the implementation is built on, with attribution to
the MIT-licensed reference implementations studied.

## Known limits

- No live editing of documents open in Word (clean refusal; COM tools work on
  saved files).
- TOC/caption-list page numbers require a field update: automatic on next Word
  open (`update_on_open`), or immediate via `com_refresh_fields`.

## License

**PolyForm Noncommercial 1.0.0** — free for personal, academic, research, and
any other noncommercial use. Using it to make money? That's fine too — just
ask first: open an issue to arrange a commercial license.
