内容
<!-- mcp-name: io.github.KitchenSink4AI/kitchensink4word -->
# 🚰 KitchenSink4Word Community Edition
[](https://github.com/KitchenSink4AI/KitchenSink4Word/actions/workflows/tests.yml)
[](https://pypi.org/project/kitchensink4word/)
[](LICENSE)
[](https://mcpservers.org/servers/nometalalchemist/kitchensink4word)
[Landing page](https://kitchensink4.ai/KitchenSink4Word/) · [llms.txt](https://kitchensink4.ai/KitchenSink4Word/llms.txt) (machine-readable capability manifest for agents and LLM crawlers)
**Edit Word documents with your AI assistant: tracked changes, citations, templates and live edits in Word.**
Edit real Word documents from Claude Code, Codex CLI, Copilot CLI or any other MCP client that runs local tools. KitchenSink4Word connects your assistant to .docx files on Windows, and can edit a document while it is open in Microsoft Word so you see the changes land. Files are processed on your computer; the only thing that leaves it is what your AI app sends to its own provider. The Community edition is free under the AGPL. The Business edition adds a Windows installer, a signed update channel, a license your company can approve and support.
**Works on:** Windows. File editing works without Microsoft Word; live editing and the Word-powered features need Word installed.
## Install
Pick the route for your AI app. The commands go in PowerShell on Windows or a terminal on macOS and Linux, not into an AI chat. The package routes need Python 3.12 or newer.
**Claude Desktop**
Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then quit and reopen Claude Desktop. Download the `.mcpb` file from [KitchenSink4Word releases](https://github.com/KitchenSink4AI/KitchenSink4Word/releases/latest). In Claude Desktop open Settings, then Extensions, then Advanced settings, then Install extension, and choose the file. The bundle fetches the Python package the first time it starts, so the first launch needs a network connection. Restart your session and check that the tools show as connected.
**Claude Code or Codex CLI**
Install uv, then run the line for your app and restart your session:
```sh
claude mcp add word -s user -- uvx kitchensink4word
```
```sh
codex mcp add word -- uvx kitchensink4word
```
**Any other local MCP client**
Use `uvx` as the command and `kitchensink4word` as its argument, or install the package and use `kitchensink4word` as the server command:
```sh
pip install kitchensink4word
```
Then follow your client's guide for adding a local MCP server. Installing the package on its own does not connect it to an AI app.
**Business edition**
Compare the editions on the [pricing page](https://kitchensink4.ai/pricing/). Already purchased? Your Windows installer and download link are in your [license portal](https://get.kitchensink4.ai/my-license/).
## What it can do
110 document tools, plus the pack on/off controls.
- Revise a report while it stays open in Word, with edits you can watch.
- Read, accept and reject tracked changes, and work through reviewer comments.
- Fill a template or assemble chapters into one manuscript.
- Build and format tables, lists, headings and page layouts.
- Insert citations, bibliographies, footnotes and cross-references.
- Find formatting, accessibility and structure problems before handoff.
- Compare documents, prepare mail merges and redact selected text.
- Import or export PDF through Word when it is installed.
What is available depends on the packs you enable and the applications installed. The full tool reference is below.
## Business edition
Need a license your company can approve and a setup someone supports? The Business edition pairs these tools with a Windows installer, a signed update channel and support under the Business terms. Update checks tell you when a covered release is available; nothing installs on its own. Compare the options on the [pricing page](https://kitchensink4.ai/pricing/). The Community edition stays free under the AGPL, including business use that meets its terms.
## Privacy Policy
The tools run on your computer, and KitchenSink4AI receives no documents and no usage data from them. Your AI app may send prompts, file contents and tool results to its own provider under that app's settings and terms. Installing downloads packages, and the Community version check contacts PyPI unless you disable it; those requests carry connection details such as your network address and never your documents. Cloud folders and backups follow their own settings. The [Privacy Policy](https://kitchensink4.ai/privacy/) covers the product, purchases and support records.
Not affiliated with, endorsed by, or sponsored by Microsoft Corporation.
Microsoft and Word are trademarks of the Microsoft group of companies.
## What the 222 operations cover
The everyday core covers text and formatting, tables (including merge-aware
column insert/delete and one-call bulk cell edits), footnotes and endnotes
(full lifecycle plus footnote and endnote conversion), TOC and caption lists,
headers, footers, and sections, images, bulleted and numbered lists, content
controls and fields, threaded comments, and tracked changes (read, accept and
reject by author, and writing edits as tracked changes). Beyond that the
surface spans equations (LaTeX to Word math), native charts, document assembly
(chapter files into one manuscript), Zotero library citations, publication
style conversion (8 styles, beta), review-cycle analytics, workflow suites
(mail merge, batch operations, redaction, compliance and accessibility audits
and fixes, submission prep, front matter, diagnostics), and Word-COM-backed
document compare, field refresh, PDF export and import, and open-clean
validation on Windows.
## What makes it different
- **Merge-aware table column operations.** `modify_table_structure` inserts
and deletes columns 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 edit tools
produces real Word revisions the recipient can accept or reject, proven
round-trip against the server's own revision engine.
- **Document compare.** `com_multi_document(action="compare")` produces a
Word-native redline between two versions of a document.
- **Never corrupts.** Atomic saves (temp file, structural validation, replace),
automatic slot 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 and replace works across Word's arbitrarily
split runs while preserving per-character formatting, with a ReDoS timeout
guard on user regex and an optional blast-radius limit.
## Why this one (the capability comparison)
Every public Word MCP server was surveyed before building this. The honest
comparison is about what each one can do, not how many names it has:
| Capability | KitchenSink4Word | GongRzhe Office-Word (2.1k★, archived) | word-mcp-live (195★) | SecurityRonin docx-mcp (43★) |
|---|---|---|---|---|
| Tiered context loading (lite core, packs on demand) | ✅ from ~10.2k tokens | ❌ | ❌ | ❌ |
| Live editing while the doc is open in Word | ✅ cursor-safe, one Ctrl+Z per call | ❌ | ✅ | ❌ |
| 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 | ✅ | ❌ | ❌ | ❌ |
Capability survey compiled from public repositories, documentation, and issue
trackers. Corrections welcome: [open an issue](https://github.com/KitchenSink4AI/KitchenSink4Word/issues).
## The packs
Numbers below come straight from `scripts/measure_surface.py`, never
hand-counted, and every one counts the whole `tools/list` entry a client
receives rather than the description and schema alone. The lite core loads at
startup; the seven packs load on demand.
| Pack | Tools | Approx tokens | What it carries |
|---|---:|---:|---|
| **lite** (startup) | 29 | ~10.2k | Everyday reading and editing: text, paragraphs, tables, cells, lists, find and replace, outline, document view, backups, workflow guide, server info, pack toggles |
| references | 8 | ~2.9k | Word-native citations and bibliography, Zotero search and cite, parity checks, style conversion and detection |
| review | 9 | ~2.4k | Tracked changes (read, accept/reject, reports), threaded comments, structured diff, anonymize and deanonymize |
| academic | 24 | ~7.6k | Footnotes and endnotes, TOC, index, captions, cross-references, front matter, chapter headers, sections, styles, list numbering, word counts, validation batteries, submission prep, accessibility |
| assembly | 7 | ~2.1k | Insert and split documents, move sections, copy tables across files, apply and fill templates, mail merge |
| media-forms | 16 | ~5.6k | Images, charts, equations, text boxes, hyperlinks, table structure and styling, form fields, content controls, field codes |
| com-live | 13 | ~3.1k | Drives a local Microsoft Word: PDF import/export, compare and combine, proofing, readability, field refresh, live editing of open documents |
| protection-io | 6 | ~1.6k | Document protection, watermarks, redaction with verification, table data import and export |
| **Full surface** | **112** | **~35.5k** | Everything (110 document tools plus `enable_tools` / `disable_tools`) |
## Quickstart: start lite, enable what you need
A session begins with the lite core. When a task needs more, the agent turns
on the pack by name:
```
enable_tools(["references"]) # citations, bibliography, Zotero
enable_tools(["academic", "review"]) # notes, TOC, tracked changes, comments
```
Lite-tool refusals name the pack and the exact `enable_tools` call to run, and
`get_workflows` recipes name the packs each workflow needs, so discovery is
built in. To skip tiering entirely, start the server with `KS4W_MODE=full` and
every tool is present from the first call.
Installed from the `.mcpb` bundle, the same two choices are checkboxes in the
server's Claude Desktop settings: "Load every tool at startup" and "Lock the
tool set at startup" (which fixes the surface so `enable_tools` refuses).
They write `KS4W_ALL_TOOLS` and `KS4W_LOCK_TOOLS`. Both take `true` or
`false`, treat empty as off, and refuse to start on anything else rather than
guessing. `KS4W_MODE` beats the first and `KS4W_PACK_POLICY` beats the second
whenever they are set, so a pinned pack list survives an install, and the
server writes one line to stderr at startup naming what decided the surface.
One tip that removes most permission pop-ups: In Claude Desktop's Tool
permissions for this server, set the Read-only tools group to Always Allow.
Those tools cannot change anything, so approving them once is safe, and Claude
stops asking about every read. Leave the acting tools on Ask, so anything that
changes things still checks with you first.
One client-side caveat: some MCP clients drop a tool's schema when a pack is
disabled and do not pick it back up on re-enable, even though the server sends
`tools/list_changed` both ways (observed in Claude Code, 2026-09). If a
re-enabled tool comes back as "no such tool", refresh the tool list on the
client side (in Claude Code, a `ToolSearch` call for the tool reloads its
schema).
## Two numbers that matter
- **222 document operations, 110 tools.** The operation count went up and the
tool count came down on purpose. v1 spread similar jobs across many
competing names; v2 gives each concept exactly one name built from a small
verb table (`insert_`, `set_`, `manage_`, `list_elements`, `validate`,
`delete_element`), so an agent picks the right tool the first time and
carries less schema to do it. Fewer tools, more reach. Measured with one
yardstick on both trees, v1.6 performed 200 operations across its 189
tools and v2.0 performs 222 across 110: every v1.6 capability survived the
consolidation (the migration map covers all 189, test-guarded) and v2 adds
the anchored batch editor, the anchored document view, deletion parity,
and wider dispatch on the multiplexers. Both figures come from
`scripts/count_operations.py`; the v1.6 run is
`scripts/count_operations_v16.py`, which measures a v1.6 checkout with the
same definition.
- **Tiered loading: starts at about 10.2k tokens, scales to everything.** A
fresh session loads the 29-tool lite core (about 10,200 tokens) and turns on
capability packs only when a task needs them, with one `enable_tools` call.
Load every pack and the full surface measures about 35,500 tokens, so a
session that never leaves lite carries roughly a quarter of the whole sink.
(All figures are script-measured and count what the client actually
receives; see [Context cost](#context-cost-measured) below.)
## Context cost (measured)
Almost no MCP server tells you what it costs to load. Here is the bill, from
`scripts/measure_surface.py`:
- **Lite start:** 29 tools, about 10,200 tokens, loaded when the session opens.
- **Full surface:** 112 tools (110 document tools plus the two pack toggles),
about 35,500 tokens with every pack enabled.
- Clients that defer tool schemas until first use (for example Claude Code)
pay close to zero until a tool is actually called.
Both figures count the entire `tools/list` entry the client receives: name,
title, description, input and output schemas, annotations and metadata. The
estimator used to sum description and input schema only, which published a
number about a quarter below what crosses the wire, and a server whose pitch
is that it tells you what it costs does not get to publish the flattering
subset. The v1.6 comparison this section used to carry was taken on that
older yardstick, so it is gone rather than restated: no v1.6 measurement
exists on this one.
## Safety model
- Every mutating tool takes `file_path` and rotates the current content into
stable backup slots before the change (`backup=False` to skip the rotation;
the atomic validated save always applies). Backups live in a hidden
`.ks4w-backups/` folder next to the document, one subfolder per document,
with exactly two slots: `prev.docx` (state before the most recent mutation)
and `anchor.docx` (session start, rotating after 60+ minutes of idle).
Storage stays bounded at roughly two copies per document no matter how many
edits a session makes. `manage_backups` lists, restores (undoably: the
pre-restore state rotates into `prev` first), and purges them, including
leftover `*.bak-*` files from earlier schemes.
- Exclude `.ks4w-backups/` from cloud sync tools (OneDrive, Dropbox, Google
Drive): the slots churn on every edit and sync clients can hold locks that
slow saves down.
- Mutations of the same file are serialized (in-process and across server
processes via an advisory lockfile), so parallel calls cannot clobber each
other and response metadata reflects settled document state.
- COM/live mutations (documents open in Word) remain outside this backup
system; Word's own AutoRecover covers the open document.
- 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` reports integrity in both directions.
- Paragraph deletion refuses ranges that would cut a field (TOC, PAGEREF) in
half or silently swallow a section break.
### Update check (opt-out)
| Variable | Effect |
|---|---|
| `KS4W_UPDATE_CHECK` | `off` turns the update check off completely: no network call, no cache file (the older `KS4W_NO_UPDATE_CHECK=1` still works) |
**Update check.** The server looks for a newer release on PyPI only when you
call `get_server_info`, never at startup and never on a timer, at most one
request every seven days, capped at two seconds. The check is a single plain HTTPS
GET to pypi.org that sends nothing but the request itself. A failed check is
reported with its reason rather than hidden. Set `KS4W_UPDATE_CHECK=off` to turn it off
completely (the older `KS4W_NO_UPDATE_CHECK=1` still works). The server never
downloads or installs anything.
### Sandboxing (opt-in)
Off by default: with nothing configured, the server behaves exactly as it
always has. Set the `KS4W_ALLOWED_ROOTS` environment variable to a list of
directories separated by the OS path separator (`;` on Windows, `:`
elsewhere), for example `%USERPROFILE%\Documents;D:\Work`, and every path the
server touches must resolve inside one of those directories. Reads are gated
as well as writes, since a read outside the sandbox exfiltrates content just
as surely as a write plants it. The containment check runs on canonicalized
paths, so `..\` traversal, symlink and junction escapes, 8.3 short names,
extended-length prefixes, case tricks, and lookalike sibling directories
(`Documents2` against an allowed `Documents`) are all caught, and UNC network
paths are refused unless an allowed root is itself a UNC path that contains
them. A blocked call refuses with a typed error naming the offending path and
the allowed roots before any file is opened. Recommended whenever the server
runs against untrusted or semi-trusted agent traffic.
## Testing
2,189 tests (2,094 run everywhere; 95 live-marked tests drive a real Word
instance on Windows): the suite was developed against a private corpus of
real-world documents (book-length chapters, a document with 171 footnotes, a
manuscript with 126 tracked changes and reviewer comments), and CI
auto-generates **structurally equivalent synthetic stand-ins**
(`tests/make_corpus.py`) so the full suite runs on any machine, including
yours and every pull request. Local real documents, when present, take
precedence. `tests/word_validator.py` opens outputs in invisible Word and
fails on any repair prompt, the definitive corruption check.
Development history: prototyped with Claude Code in a day (2026-08-27), then
hardened across release cycles through dedicated adversarial rounds (scale
torture, pathological merge topologies, Unicode and schema fuzzing, ReDoS,
Word-lock lifecycle, live-editing interaction hunts, COM leak checks) plus
per-phase unit gates. Every finding fixed with a regression test, same session
it was found. `research/` documents the OOXML algorithms and pitfalls the
implementation is built on, with attribution to the MIT-licensed reference
implementations studied.
## Maturity: what the version number does and does not claim
This project moves fast and is honest about what backs it. What the test
record covers: every release passes the full suite plus dedicated adversarial
rounds through the raw MCP transport, against a corpus of long, heavily
formatted real-world documents with zero corruption across all of it. What it
does not yet cover: other machines, Word builds older than current Microsoft
365, non-English Word installs (some tools reference styles by localized
display name), RTL scripts, and the diversity of documents only real users
bring. The safety net while the tool earns that mileage is structural:
automatic slot backups before every mutation and atomic validated saves, so a
bad outcome is a restore, not a loss. If something misbehaves on your
documents, [an issue](https://github.com/KitchenSink4AI/KitchenSink4Word/issues)
with the symptom (never the document itself, unless it contains nothing
private) is the most valuable thing you can send. Before filing: ask your AI
to run `get_server_info` and paste the output here; it is designed to be safe
to share.
**Beta-labeled tools**, heuristic by nature: review their flagged-items list
rather than trusting silently: `convert_citation_style`,
`anonymize_for_review`, `validate(checks=["defined_terms"])`, and the
text-reference scan inside `validate(checks=["cross_references"])`. Each
returns an explicit list of what it could not confidently handle.
<!-- LIVE_MATRIX:START (generated by scripts/generate_live_matrix.py) -->
## Live-mode capability matrix
Which tools work on a document that is OPEN in Word. Dual-mode tools auto-route (`live='auto'`); everything else refuses with `DOCUMENT_LOCKED` until the file is closed. Word COM calls within one server process are serialized. Live calls and passwordless save or close also use a machine-local cross-process lock; a concurrent caller receives `APP_BUSY` before touching Word and nothing is queued. Live edits stay unsaved until `com_save_document` (the Option C model: see `get_workflows(task='live-editing')`).
| Dual-mode tool (file + live) | Live-mode notes |
|---|---|
| `apply_edits` | one COM undo group; markdown lists/pipe tables in insert ops refuse up front with a close-the-file hint; replace verifies matched text in the live range; all other index-addressed ops run the snapshot staleness guard against the last saved state |
| `delete_paragraphs` | section-break/field-crossing ranges refuse; range={} location endpoints run the snapshot staleness guard |
| `find_text` | plain queries, 500-match cap; formatting mode and include_textboxes file-mode only |
| `format_text` | formatting mode routes live; case mode file-mode only (live='force' refuses); range={} locations run the snapshot staleness guard |
| `get_comments` | same shape |
| `get_document_info` | same key names; adds words/track_revisions, omits part list |
| `get_outline` | same flat-list shape |
| `get_text` | body shape identical; include_textboxes/textbox modes file-mode only |
| `insert_paragraphs` | heading_level maps to built-in Heading styles by numeric constant (outline-based docs get direct outline levels); inherit_format/copy_format_from file-mode only; text-selector locations run the snapshot staleness guard |
| `search_and_replace` | plain items route live (255-char finds handled); preview and find_formatting modes are file-mode only (find_formatting with live='force' refuses) |
| `set_cells` | plain text cells; vertical merges refuse live |
| `set_paragraph_format` | shading/borders/tab_stops keys refuse live (XML-level); raw indices keep the v1 index-trust contract |
| `set_paragraph_text` | expect guard honored; tracked-revision paragraphs refuse; text-selector locations run the snapshot staleness guard |
| `word_count` | Word's own statistics engine; exclusions mode file-mode only |
**Live-only tools** (need the document open): `live_insert_at_cursor`, `live_repair`, `live_scroll_to`, `live_set_track_changes`.
**COM tier** (drive the Word application, open or closed): `com_export_pdf`, `com_import_pdf`, `com_multi_document`, `com_proofing_errors`, `com_readability_statistics`, `com_refresh_fields`, `com_save_document`, `com_validate_opens_clean`, `com_word_status`.
**Open-document reader**: `get_document_view` (reads the last SAVED state and says so).
The remaining 63 writers and 14 readers are file-only: they refuse while the document is open (close it, or `com_save_document` with `close=true`). The full per-tool table lives in `docs/internal/live_parity_v2.md`.
<!-- LIVE_MATRIX:END -->
## Known limits
- Live regex replacements skip matches positioned after complex fields in a
story (COM character offsets drift there); the skip count is reported and a
literal find still works. Live `set_cells` refuses vertically merged tables
(the file-based tool is merge-aware; close the doc for those).
- Live tracked-change attribution is best-effort: Word signed into an Office
account attributes revisions to that account; results report the effective
author honestly.
- TOC and caption-list page numbers require a field update: automatic on next
Word open, or immediate via `com_refresh_fields`.
## Upgrading from v1.x
Every v1.x tool name changed. The 189-tool v1.6 surface was rebuilt as a
consolidated set of 110 tools that cover every prior capability under one
grammar. If you are upgrading from v1.x, read the
**[migration guide](docs/MIGRATION_V2.md)** first: it maps every old tool
name to its v2 home, and `get_workflows("migrate-from-v1")` returns the
same map in-session. New installs need nothing extra.
## License
KitchenSink4Word is dual-licensed:
**AGPL-3.0 (open source).** Free for anyone (individuals, academics, and
businesses) for any use that complies with the AGPL's terms. Those terms
include sharing source, including your modifications, when you distribute the
software or make it available over a network.
**Commercial license.** For organizations that want to build KitchenSink4Word
into their own products or services without the AGPL's source-sharing
obligations. Contact licensing@kitchensink4.ai.
Copyright (c) 2026 Alvut Consulting, LLC. KitchenSink4AI is a product line of
Alvut Consulting, LLC.
Not affiliated with, endorsed by, or sponsored by Microsoft Corporation.
Microsoft and Word are trademarks of the Microsoft group of companies.
---
*Not affiliated with or endorsed by Microsoft Corporation. Microsoft and Word
are trademarks of Microsoft Corporation. "For Microsoft Word" describes
file-format compatibility only.*
连接信息
猜你喜欢
暂无推荐服务器