# KitchenSink4Word

> Word (.docx) MCP server for agents. 115 operations in 10 tools (231 counting each action), about 9.1k tokens for the whole tool list, everything available from the first message. stdio. Every mutation is preceded by an automatic backup and committed by an atomic verified save. Ambiguous targets are refused with every candidate listed instead of guessed.

Release: v3.0.0
MCP registry name: io.github.KitchenSink4AI/kitchensink4word
Transport: stdio.
Platform: Windows. Editing files works without Word installed. Live editing and the Word-powered features need Microsoft Word.
The `com_*` and `live_*` operations drive a local Microsoft Word through COM.

This document is written for the agent that will call these tools. Every line
below is a behavior you can rely on without testing it first.

## 1. How the surface works

The server lists ten tools: `word_read`, `word_edit`, `word_format`, `word_structure`, `word_media`, `word_review`, `word_references`, `word_document`, `word_app` and `word_help`. Each tool except `word_help` takes `{op, args}`: `op` names an operation listed in that tool's description, and `args` holds its arguments, including `file_path` (the absolute path of the .docx). Call `word_help` with an `op` to get that operation's arguments and a worked example, or with `topic='location'` for the `location` object. Every operation has a curated example.

- All 115 operations are available from the first message. There is nothing to enable and no tool-set switching, and the tool list is the same for the whole session (the server sends no `tools/list_changed`).
- About 9.1k tokens (about 9,082 approximate tokens, measured over real stdio by `scripts/measure_surface.py`) cover the whole tool list; the server's own instructions add about 500. Per tool, operations and tokens: `word_read` 24 / 1,368, `word_edit` 9 / 1,031, `word_format` 6 / 620, `word_structure` 15 / 1,025, `word_media` 12 / 906, `word_review` 7 / 787, `word_references` 13 / 1,032, `word_document` 15 / 1,030, `word_app` 14 / 1,070, `word_help` 0 / 213.
- Routing is lenient and meaning is strict. Op names match without regard to case, underscores or hyphens; arguments may sit beside `op`; `path` or `file` stands for `file_path`; an op sent to a tool that does not hold it runs when that tool promises no less. Each correction is echoed under `normalized_from`. A value that means something different from what you asked, and a close but different op name such as `insert_paragraph`, are refused, and an unknown op answers up to three `did_you_mean` suggestions that are never run.
- Reads are token-shaped on purpose: `get_document_view` projects a document with stable anchors instead of dumping it, says what it left out, and returns `too_large: true` with the outline when one answer cannot hold the whole document. Prefer it, then `apply_edits`, over many small reads and writes.
- Clients that defer tool schemas until first call pay close to zero at startup.
- Launch settings can narrow the surface. `KS4W_READ_ONLY=1` lists only the operations that read. `KS4W_FORBID` removes named tools or operations from the list and from help; `KS4W_FORBID=word_app` closes every route to the running Word, including the live routes of other operations. A call refused because of a launch setting returns `NOT_AVAILABLE`, and no tool call can undo it. What is removed no longer counts toward the token figure.
- Settings from earlier versions are handled for you: an old default (`KS4W_MODE=lite`, `full` or `everything`, `KS4W_PACK_POLICY=auto`, `KS4W_ALL_TOOLS`, `KS4W_LOCK_TOOLS` off) is ignored with a one-line notice on stderr, and a setting that locked the tools (`KS4W_PACK_POLICY=locked`, `KS4W_LOCK_TOOLS` on or a `KS4W_MODE` list of tool groups) stops the start with exit status 2 and one line naming the variable and its replacement, `KS4W_READ_ONLY` or `KS4W_FORBID`.

## 2. Behavioral contracts

- Backup before mutation: every file mutation writes a backup into bounded rotating slots first. `manage_backups` lists, restores, and prunes them. The destructive operations `redact_text`, `resolve_revisions`, `prepare_for_submission`, `anonymize_for_review` and `set_document_protection` also keep a labeled snapshot, named in `snapshot` and restorable with `manage_backups` and `source=<label>`.
- Atomic verified save: the write goes to a temporary file, the result is re-opened and validated, then swapped in. A failed operation leaves the original byte-identical. A call that changes nothing writes nothing, rotates no backup and answers `unchanged: true`.
- Untouched content passes through byte-identical, including equations, textboxes, content controls, and every part the call did not address.
- Batches are all-or-nothing: `apply_edits` validates the whole batch first, applies every edit in one save, or mutates nothing. One refusal carries every failing operation with its index, its address, and its reason, so the batch is corrected once and resent whole.
- Closed error vocabulary: every refusal is `{ok: false, error: {code, message, hint, details}}`. `code` is one of the 19 values in Section 5. Branch on `code`, never on message text. Anything unexpected answers `INTERNAL_ERROR` with internal details scrubbed.
- Refusals ride the wire with `isError=true`. A refusal never arrives as a success.
- `hint` carries the next call to make, not a restatement of the failure. A refusal that points to other operations lists them under `details.see_ops`, each with its tool.
- Every answer is one compact JSON block that keeps `ok` and `file`.
- 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.
- Pending Word dialogs are detected at the OS window level, not inferred from a timeout. `com_word_status` reports the dialog a human has to dismiss, and a live edit while Word shows a dialog answers `APP_BUSY` naming it.
- File-mode operations refuse a document that is open in Word and name the `live_*` or `com_*` route that handles the open case.
- Live edits land as one Ctrl+Z step per call and leave the user's cursor and selection where they were.
- Tracked-changes authoring is a parameter, not a mode: pass `track=true` to a text mutation and the edit is written as a revision. A document saved with Track Changes on records edits as revisions unless the call passes `track=false`. With no `author`, tracked changes and comments are signed with the user's own Office user name (then the Windows sign-in name, then `Author`; never an email address); `KS4W_AUTHOR=assistant` signs "AI Assistant via KS4Word", a call can ask for the same name with `author="assistant"` (any case), and any other `author` in a call wins, except an email address, which is never written into a document (the default signs instead, and the answer says so).
- Document protection is honored: on a `read_only` document, writes refuse `PROTECTED` and the file stays byte-identical; a `tracked_changes` document takes only tracked edits; a `comments` document takes only `manage_comment`; a `forms` document takes only form operations. `set_document_protection` and `manage_backups` stay callable so protection can be lifted and a backup restored.
- Ambiguity is refused, never guessed: `format_text` with `find` and no `occurrence` refuses `AMBIGUOUS_LOCATION` and lists every match; `occurrence` picks one and `"all"` takes every match.
- Every call runs under one deadline (`KS4W_CALL_TIMEOUT_S`, default 300 seconds). A file edit that answers `TIMEOUT` saved nothing; work handed to Word may still finish, so check the document before retrying.
- Output is bounded (`KS4W_MAX_OUTPUT_CHARS`, default 80,000 characters). A reply that would pass the ceiling is cut where it can be, carries a `page` block naming what was cut and how to continue, and when nothing is cuttable the call refuses `LIMIT_EXCEEDED`.
- The server never ends a Word process by name. At exit it ends a hidden Word it started for a stuck worker only when the recorded process id and creation time still match, the image is `WINWORD.EXE` and the command line reads `/Automation`.
- Encrypted files are refused before the hidden Word starts, so no password dialog appears on the user's desktop.
- Test evidence for v3.0.0: 4,384 tests, including adversarial cases driven through the raw MCP stdio transport and hidden-Word runs; outputs are verified by opening them in invisible Word and failing on any repair prompt.

## 3. Addressing model

- Positional operations take one `location` object carrying exactly one selector: `paragraph` index, `after_heading`, `outline` path, `bookmark`, `search` text, `anchor` or `cursor`. A position modifier (`before`, `after`, `replace`, `start`, `end`) selects placement relative to the resolved target.
- Paragraph numbers count body paragraphs from 0, tables not included, and an insert at `{"paragraph": N}` goes after paragraph N.
- `insert_paragraphs`, `insert_image` and `create_table` also write into a header or footer: `{"header": {"section": 0, "ref_type": "default"}}` (or `"footer"`). Alone it means the end of the part, with `position` `start` the start, and a selector beside it is resolved inside the part. A part that does not exist yet is created.
- `get_document_view` returns content with stable anchors. Anchors survive edits made elsewhere in the document. Feed them straight back into `apply_edits`.
- An anchor that no longer resolves returns `STALE_ANCHOR` and the view call to re-run. It never falls back to a nearby target.
- Text that matches more than one place returns `AMBIGUOUS_LOCATION` and lists every candidate (paragraph or table cell, with context) in `error.matches`. When the user's words do not pick a match, ask the user.
- An index past the end returns `RANGE_OUT_OF_BOUNDS` with the valid range.
- `list_elements(type=...)` enumerates any collection and returns each element with the address its own editing tools accept.
- Table cells are addressed `{row, cell}`; an unknown key refuses and names the shape.
- Read once, edit in bulk: one `get_document_view` plus one `apply_edits` replaces a read-modify-verify loop per edit.

## 4. Recipes

`get_workflows()` returns the recipe list. `get_workflows(task="<name>")` returns ordered steps, the tool and op for each step, why the step exists, and the documented traps for that sequence. All 13 recipes are named in the `get_workflows` description.

- `process-feedback`: reviewer revisions and comments, end to end, ending in a validation pass.
- `prepare-submission`: snapshot, validate, count, clean, optionally anonymize, then re-validate because the cleanup is itself a mutation.
- `format-citations`: change citation style without splitting a reference manager's bibliography.
- `build-from-template`: template to filled document.
- `heavy-editing`: sustained editing on a dated copy at file-mode speed while the user keeps the original open in Word.
- `live-editing`: editing a document open in Word, including the save-then-view ordering trap.
- `bulk-edit`: many addressed edits in one atomic pass.
- `comment-partner`: the human leaves a Word comment addressed to the AI, the agent reads the anchored context, makes the fix as a tracked change, saves, then replies and resolves. Preview recipe on shipped tools.
- `merge-chapters`: several chapter files into one manuscript with the source formatting intact, then the generated lists rebuilt.
- `build-lists-without-heading-styles`: a TOC or caption list for a document that formats headings directly.
- `merge-reference-lists`: several chapters' reference lists into one without losing run formatting or duplicating entries.
- `migrate-from-v2`: every 2.2.1 tool mapped to its 3.0 tool and op, with changed arguments, returned in-session. Same data as `migration/v2_to_v3.json` and `docs/surface_map.md`.
- `migrate-from-v1`: every v1.6 tool name mapped to its v2 home. Same data as `migration/v1_to_v2.json`; the prose version is `docs/MIGRATION_V2.md`.

## 5. Documented refusals

These are contracts. Handle them; do not retry blindly. The 19 closed codes:

- `AMBIGUOUS_LOCATION`: several targets matched. The error lists them with disambiguating addresses. Re-issue with one, or ask the user.
- `NOT_FOUND`: the target does not exist. Re-run `get_document_view` or `get_outline` for current content and anchors. A path that does not exist gets its own hint, an unknown paragraph style lists the nearest names, and an unknown op points you to `word_help`.
- `STALE_ANCHOR`: the document changed since the view was taken. Re-run `get_document_view` and resend with fresh anchors; after live edits, `com_save_document` first.
- `RANGE_OUT_OF_BOUNDS`: the range exceeds the document; the message names the valid bounds.
- `DOCUMENT_LOCKED`: the file is open in Word or held by another process, which the message names. Close it and retry, or use the live route.
- `VALIDATION_FAILED`: the produced package failed its post-write check. The original was NOT modified.
- `UNSUPPORTED_CONTENT`: protected, damaged or structurally unsupported content, or a file Word has on record as having stopped Word while it opened, refused instead of written partially. The message names the remedy.
- `PROTECTED_VIEW`: click Enable Editing in Word first.
- `APP_NOT_RUNNING`: the operation needs Word installed and reachable.
- `APP_BUSY`: Word is in use or showing a dialog; the message says which. Clear it and retry.
- `APP_BLOCKED`: Word is not answering. When `details.cancelled` is true, the server's hidden Word was ended and nothing was saved: after a dialog, answer it in Word first; otherwise retry with a larger timeout. When it is false the operation may still be running: do not retry yet, wait until `com_word_status` shows no COM operation in progress, then check the output file. `details.saved` and `details.may_still_save` say whether anything had been saved and whether it still may be.
- `CONFLICT`: the target already exists or holds content the call would remove (such as a header picture), or the document open in Word changed or disconnected during the call. Nothing was changed.
- `BAD_PARAMS`: the request did not fit the op, including an unknown argument, a folder given as a file, a write sent through `word_read`, or a path outside the sandbox. `word_help` with the op gives its arguments and an example.
- `NOT_AVAILABLE`: this server's launch settings turned the operation off, usually by IT. No tool call can turn it back on.
- `TIMEOUT`: the call ran past its time limit and was stopped. A file edit that times out saves nothing.
- `INTERNAL_ERROR`: something inside the server failed; the arguments were not the cause. Try once more, and if it repeats, report it with the version from `get_server_info`.
- `LIMIT_EXCEEDED`: the answer would pass the output limit, or the input passes an op's limit (LaTeX over 20,000 characters, which the hint says how to split). Narrow the request.
- `PROTECTED`: the document's editing restriction, or the file's read-only setting, does not allow this change. `set_document_protection` with `protection='none'` lifts a restriction. A read-only file is cleared in its Properties, or copied with `copy_document` (the message proposes a name) and the copy edited, and the user is told the copy's name and why.
- `GUARD_TRIPPED`: a safety check you passed (`expect`, `expect_start`, `expect_end` or `max_replacements`) did not hold, so nothing changed. Read the document again and resend with matching values.

Refusals are the reliability feature, not the failure mode. A refusal names
what was wrong, leaves the file untouched, and carries the next call in
`hint`. Retrying the same call unchanged is never the fix.

Other documented behavior:

- A view taken before `com_save_document` does not see unsaved live edits. Save, then view, then edit.
- `diagnose_document` reads saved XML and has no live route. Save first; `com_validate_opens_clean` checks the open copy instead.
- Sandbox mode, when enabled (`KS4W_ALLOWED_ROOTS`): paths outside the configured roots refuse with `BAD_PARAMS`.

## 6. Inventory: 115 operations in 10 tools

### `word_read`: 24 operations
`get_text`, `get_document_view`, `find_text`, `list_elements`, `get_headers_footers`, `get_document_info`, `com_word_status`, `validate`, `diagnose_document`, `get_workflows`, `get_styles`, `get_outline`, `get_table`, `get_comments`, `get_tracked_changes`, `get_server_info`, `structured_diff`, `get_paragraph_format`, `word_count`, `get_revision_report`, `comment_report`, `get_protection`, `detect_citation_system`, `parse_references`.

### `word_edit`: 9 operations
`insert_paragraphs`, `search_and_replace`, `delete_paragraphs`, `insert_break`, `apply_edits`, `delete_element`, `stamp_anchors`, `set_paragraph_text`, `redact_text`.

### `word_format`: 6 operations
`define_style`, `apply_style`, `format_text`, `set_paragraph_format`, `change_heading_level`, `apply_manuscript_format`.

### `word_structure`: 15 operations
`set_header_footer`, `set_section_properties`, `insert_list`, `create_table`, `set_table_properties`, `set_cells`, `delete_table`, `modify_table_structure`, `format_cells`, `sort_table`, `import_table`, `set_list_numbering`, `set_page_numbers`, `setup_chapter_headers`, `move_section`.

### `word_media`: 12 operations
`insert_image`, `insert_field`, `set_image`, `export_images`, `insert_chart`, `set_chart_data`, `insert_equation`, `set_textbox_text`, `insert_hyperlink`, `insert_content_control`, `set_content_control`, `set_form_fields`.

### `word_review`: 7 operations
`manage_comment`, `resolve_revisions`, `anonymize_for_review`, `deanonymize_document`, `prepare_for_submission`, `set_track_changes`, `retrack_changes`.

### `word_references`: 13 operations
`manage_note`, `insert_caption`, `insert_reference_list`, `insert_bookmark`, `convert_notes`, `insert_cross_reference`, `mark_index_entry`, `insert_citation`, `insert_zotero_citation`, `search_zotero_library`, `manage_source`, `set_bibliography_style`, `convert_citation_style`.

### `word_document`: 15 operations
`insert_document`, `copy_document`, `create_document`, `manage_backups`, `set_document_properties`, `split_document`, `copy_table`, `apply_template`, `fill_template`, `mail_merge`, `assemble_front_matter`, `set_document_protection`, `set_watermark`, `fix_accessibility`, `export_table`.

### `word_app`: 14 operations, Windows with Word only (except `update_now` and `update_notices`)
`com_save_document`, `live_insert_at_cursor`, `live_set_track_changes`, `com_refresh_fields`, `com_validate_opens_clean`, `com_multi_document`, `com_import_pdf`, `com_export_pdf`, `live_scroll_to`, `live_repair`, `com_proofing_errors`, `com_readability_statistics`, `update_now`, `update_notices`.

### `word_help`: 0 operations
Returns the arguments and a worked example for any operation, and explains the `location` object.

### Operations that take an action
- `list_elements(type=...)`: enumerates tables, images, charts, footnotes, endnotes, sources, bookmarks, sections, fields, equations, form fields, content controls, lists, TOC entries, and more.
- `validate(checks=[...])`: 14 correctness batteries, `core`, `captions`, `chapter_headers`, `cross_references`, `notes`, `forms`, `citation_parity`, `defined_terms`, `brand`, `template`, `reference_fields`, `image_resolution`, `accessibility`, `redaction`.
- `manage_note`, `manage_comment`, `manage_source`, `manage_backups`: lifecycle verbs on one object family per operation.
- `modify_table_structure(action=...)`: insert and delete rows and columns, merge, unmerge, split.
- `delete_element(type=...)`: one delete for any addressable element.
- `com_multi_document(action=...)`: compare, combine, or merge documents through Word.

The operations figure is produced by `scripts/measure_surface.py` (115 over real stdio). The figure that counts each action separately, 231, is produced by `scripts/count_operations.py`, which reads the dispatch values each operation actually validates out of committed source. Its docstring carries the counting definition and the exclusions.

## 7. Upgrading

Version 3.0 regroups the 112 flat tools of 2.2.x into the ten tools above. Every 2.2.1 operation keeps its name except `enable_tools` and `disable_tools`, which are gone because nothing needs enabling. Call a former tool as an operation of the tool that now holds it: `word_edit` with `op: "insert_paragraphs"` replaces the tool `insert_paragraphs`. The map is `docs/surface_map.md` in the repository, `migration/v2_to_v3.json`, and `get_workflows(task="migrate-from-v2")`, which also lists the changed arguments: `after_anchor` is now `after_text`, `anchor_text` is now `at_text`, `set_document_protection` takes `read_only` and `tracked_changes`, and list and page-number formats are snake_case (the old spellings still work and are echoed under `normalized_from`). `stamp_anchors` moved from `get_document_view` to its own `word_edit` operation.

Upgrading from v1.x: call `get_workflows("migrate-from-v1")`, or read `migration/v1_to_v2.json` or `docs/MIGRATION_V2.md`, then map the 2.x name through the 3.0 map above. New installs need nothing.

## 8. Install

- Claude Desktop: download the `.mcpb` bundle from the latest GitHub release and open it. Requires `uv` on PATH.
- Claude Code: `claude mcp add word -s user -- uvx kitchensink4word`
- pip: `pip install kitchensink4word`
- uvx, no install: `uvx kitchensink4word`
- Any MCP client: run the `kitchensink4word` (or `word-mcp`) executable over stdio, for example `{"mcpServers": {"word": {"command": "kitchensink4word"}}}`

Environment: `KS4W_READ_ONLY`, `KS4W_FORBID`, `KS4W_ALLOWED_ROOTS` (an
`os.pathsep`-separated path sandbox, gating reads as well as writes),
`KS4W_AUTHOR`, `KS4W_CALL_TIMEOUT_S`, `KS4W_MAX_CALL_TIMEOUT_S`,
`KS4W_MAX_OUTPUT_CHARS`, `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), `KS4W_UPDATE_NOTICES` (`off` turns
update notices off and keeps the check; `on` turns them back on).

Update notices: at most once a week, after a tool call, the server asks PyPI in
the background which version is newest; the request names only the package and
the installed version. When a newer version exists, a client with form
elicitation shows a dialog (Update now / Not now) after a read when the server
runs from uvx or the Claude Desktop bundle; otherwise a read result gets one
`update` field, to relay once. `word_app` `update_now`
installs the new version only when the user asks or agrees, and `update_notices`
(`on`, `off`, `status`) changes the setting from any client. It never downloads or
installs a new version unless the user chooses Update now in its notice or asks
the AI to update it.

## 9. Known limits

- Live regular-expression replacements skip matches that sit after complex fields in the same story; the skip count is reported and a plain-text find still works.
- Live `set_cells` refuses tables with vertically merged cells; the file-mode operation handles them.
- Live tracked-change attribution follows Word: the result's `tracked_as` says who Word signed as, and `author_source` says where that name came from.
- Table of contents and caption-list page numbers need a field update: automatic the next time Word opens the file, or `com_refresh_fields`. Page-number fields in headers and footers keep their stored text until Word lays the pages out.
- A content control bound to the document's custom XML shows the text saved in the file; Word fills it from the stored data when the file opens, so the two can differ.
- A few operations slow down sharply on extreme documents. `retrack_changes` on a paragraph of 100,000 characters or more with a paragraph added after it takes over a minute and grows quickly with the length, and `set_header_footer` on a document with a thousand sections takes minutes. A call that reaches the time limit stops with an error and leaves the file unchanged.
- In a document on disk, built-in styles are found by the English names Word keeps in every language (`heading 2`, `Caption`) or by the document's own style IDs; a name in another language (`Überschrift 2`) is refused with the document's style IDs listed. On a document open in Word, a style name goes to Word as given, so a Word installed in another language may need its own name for the style.
- `convert_citation_style`, `anonymize_for_review`, `validate(checks=["defined_terms"])` and the text-reference scan in `validate(checks=["cross_references"])` are heuristic and return a list of what they could not handle with confidence.

## 10. Links

- GitHub: https://github.com/KitchenSink4AI/KitchenSink4Word
- PyPI: https://pypi.org/project/kitchensink4word/
- Migration guide (1.x to 2.x): https://github.com/KitchenSink4AI/KitchenSink4Word/blob/main/docs/MIGRATION_V2.md
- Surface map (2.2.1 to 3.0): https://github.com/KitchenSink4AI/KitchenSink4Word/blob/main/docs/surface_map.md
- Landing page: https://community.kitchensink4.ai/word/
- Family: https://community.kitchensink4.ai/
- Issues, including licensing: https://github.com/KitchenSink4AI/KitchenSink4Word/issues/new/choose

## 11. License

AGPL-3.0. Free for any use that meets the AGPL's terms, including its
source-sharing obligations. A company shipping this in a closed product of its
own needs a commercial license, with terms worked out case by
case, arranged here:
https://github.com/KitchenSink4AI/KitchenSink4Word/issues/new?template=commercial_license.yml

## 12. Trademarks

Not affiliated with or endorsed by Microsoft Corporation. Microsoft and Word
are trademarks of Microsoft Corporation. References to Microsoft Word describe
file-format compatibility only.