# KitchenSink4Word > Word (.docx) MCP server for agents. 221 operations across 110 tools, one verb > grammar. Windows, stdio. Every mutation is preceded by an automatic backup and > committed by an atomic verified save. Release: v2.1.0 MCP registry name: io.github.nometalalchemist/kitchensink4word Transport: stdio. Platform: Windows. File-mode tools run without Microsoft Word installed. The `com_*` and `live_*` tools 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. Token economics - Session start loads 29 tools, about 8,000 tokens. Nothing else is on the wire until you ask for it. - `enable_tools([""])` adds a pack mid-session. `disable_tools([...])` removes one. Both take effect on the next `tools/list`, announced by `tools/list_changed`. - Pack costs, from `scripts/measure_surface.py`: references 8 tools / 2.4k, review 9 / 1.8k, academic 24 / 6.0k, assembly 7 / 1.7k, media-forms 16 / 4.6k, com-live 13 / 2.2k, protection-io 6 / 1.2k. - Everything enabled: 112 tools (110 document tools plus the two pack toggles), about 27,800 tokens. - Set `KS4W_MODE=full` at server start to skip tiering and load every pack at startup. - `KS4W_ALL_TOOLS=true` does the same from the `.mcpb` "Load every tool at startup" checkbox; `KS4W_LOCK_TOOLS=true` fixes the surface at startup so `enable_tools` refuses. Both accept `true`/`false`, treat empty as false, and refuse an unrecognized value at startup. There is no per-pack startup toggle by design: the client's own tool permissions and `enable_tools` already cover that ground. - Startup precedence: `KS4W_MODE` (non-empty) beats `KS4W_ALL_TOOLS` beats lite; `KS4W_PACK_POLICY` beats `KS4W_LOCK_TOOLS`. One stderr line at startup names what decided the surface. - A lite tool asked for out-of-scope work returns the pack name and the exact `enable_tools` call to run. You never have to guess which pack holds a capability. - `get_workflows` recipes name the packs each recipe needs before its first step. - Clients that defer tool schemas until first call pay close to zero at startup. - Client caveat: some clients drop a disabled tool's schema and do not re-register it on re-enable. If a re-enabled tool reports "no such tool", refresh the client's tool list. ## 2. Behavioral contracts - Backup before mutation: every file mutation writes a backup into bounded rotating slots first. `manage_backups` lists, restores, and prunes them. - 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. - 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}}`. `code` is one of 13 values: `AMBIGUOUS_LOCATION`, `NOT_FOUND`, `STALE_ANCHOR`, `RANGE_OUT_OF_BOUNDS`, `DOCUMENT_LOCKED`, `APP_NOT_RUNNING`, `APP_BUSY`, `APP_BLOCKED`, `PROTECTED_VIEW`, `VALIDATION_FAILED`, `UNSUPPORTED_CONTENT`, `CONFLICT`, `BAD_PARAMS`. Branch on `code`, never on message text. - 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. - COM access is serialized: concurrent tool calls against one Word instance are queued, so two agents working at once cannot interleave writes into the same document. Serialization spans separate server processes, not only threads in one, so two agents on two clients queue the same way. - 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. - File-mode tools 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 tool call and leave the user's cursor and selection where they were. - Tracked-changes authoring is a parameter, not a mode: pass `track=true` and an author name to a text mutation and the edit is written as a revision. - Test evidence for v2.1.0: 1,842 tests, adversarial rounds driven through the raw MCP stdio transport, zero corruptions, outputs verified by opening them in invisible Word and failing on any repair prompt. ## 3. Addressing model - Positional tools take one `location` object. Forms: `paragraph` index, `after_heading`, `outline` path, `bookmark`, `search` text, `anchor`, `cursor`. A position modifier selects placement relative to the resolved target. - `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 with the address that would disambiguate it. The wrong target is never silently edited. - 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. - 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("")` returns ordered steps, the tool for each step, why the step exists, the packs required, and the documented traps for that sequence. - `process-feedback`: reviewer revisions and comments, end to end, ending in a validation pass. - `prepare-submission`: 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. - `migrate-from-v1`: every v1.6 tool name mapped to its v2 home, returned in-session. 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. - Ambiguous target: refuses and lists the candidates with their addresses. - File-mode tool against a document open in Word: refuses and names the live route. - Word held behind a modal dialog: `APP_BLOCKED`, with the dialog reported. A human dismisses it; `live_repair` clears crashed-client state. - Word busy with another call: `APP_BUSY`. Retry after the in-flight call returns. - Protected View: `PROTECTED_VIEW`. The file has to be trusted in Word first. - Password-protected or structurally unsupported content: `UNSUPPORTED_CONTENT` instead of a partial write. - Existing destination path: `CONFLICT` unless overwrite was requested. - Sandbox mode, when enabled: paths outside the configured roots refuse with `BAD_PARAMS`. - `diagnose_document` reads saved XML and has no live route. Save first; `com_validate_opens_clean` checks the open copy instead. - A view taken before `com_save_document` does not see unsaved live edits. Save, then view, then edit. ## 6. Inventory: 221 operations, 110 tools, 8 packs ### lite core: 29 tools, 76 operations, loaded at startup `create_document`, `copy_document`, `get_document_info`, `get_document_view`, `get_outline`, `get_text`, `find_text`, `search_and_replace`, `insert_paragraphs`, `delete_paragraphs`, `set_paragraph_text`, `set_paragraph_format`, `format_text`, `apply_style`, `insert_list`, `insert_break`, `create_table`, `get_table`, `set_cells`, `delete_table`, `delete_element`, `list_elements`, `apply_edits`, `diagnose_document`, `manage_backups`, `get_workflows`, `get_server_info`, `enable_tools`, `disable_tools`. ### references: 8 tools, 9 operations `insert_citation`, `manage_source`, `set_bibliography_style`, `insert_zotero_citation`, `search_zotero_library`, `convert_citation_style`, `detect_citation_system`, `parse_references`. ### review: 9 tools, 15 operations `get_tracked_changes`, `resolve_revisions`, `get_revision_report`, `get_comments`, `manage_comment`, `comment_report`, `structured_diff`, `anonymize_for_review`, `deanonymize_document`. ### academic: 24 tools, 63 operations `manage_note`, `convert_notes`, `insert_reference_list`, `insert_caption`, `insert_cross_reference`, `insert_bookmark`, `mark_index_entry`, `assemble_front_matter`, `setup_chapter_headers`, `change_heading_level`, `get_styles`, `define_style`, `get_paragraph_format`, `apply_manuscript_format`, `get_headers_footers`, `set_header_footer`, `set_page_numbers`, `set_section_properties`, `set_document_properties`, `word_count`, `validate`, `prepare_for_submission`, `fix_accessibility`, `set_list_numbering`. ### assembly: 7 tools, 7 operations `insert_document`, `split_document`, `move_section`, `copy_table`, `apply_template`, `fill_template`, `mail_merge`. ### media-forms: 16 tools, 26 operations `insert_image`, `set_image`, `export_images`, `insert_chart`, `set_chart_data`, `insert_equation`, `set_textbox_text`, `insert_hyperlink`, `modify_table_structure`, `set_table_properties`, `format_cells`, `sort_table`, `insert_field`, `insert_content_control`, `set_content_control`, `set_form_fields`. ### com-live: 13 tools, 17 operations `com_word_status`, `com_refresh_fields`, `com_export_pdf`, `com_import_pdf`, `com_multi_document`, `com_proofing_errors`, `com_readability_statistics`, `com_save_document`, `com_validate_opens_clean`, `live_insert_at_cursor`, `live_scroll_to`, `live_set_track_changes`, `live_repair`. ### protection-io: 6 tools, 8 operations `set_document_protection`, `get_protection`, `set_watermark`, `redact_text`, `import_table`, `export_table`. ### Multiplexers: where the extra operations live - `list_elements(type=...)`: enumerates tables, images, charts, footnotes, endnotes, sources, bookmarks, sections, fields, equations, form fields, content controls, lists, TOC entries, and more, in place of 18 separate listing tools. - `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 tool. - `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. ## 7. Version and migration v2.0.0 renamed every tool. Measured with one definition on both trees, v1.6 performed 200 operations across 189 tools; v2.0 performs 221 across 110. Every v1.6 capability is mapped into v2 and the operation count went up. Upgrading from v1.x: call `get_workflows("migrate-from-v1")`, or read `migration/v1_to_v2.json` or `docs/MIGRATION_V2.md`. 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"}}}` ## 9. Links - GitHub: https://github.com/KitchenSink4AI/KitchenSink4Word - PyPI: https://pypi.org/project/kitchensink4word/ - Migration guide: https://github.com/KitchenSink4AI/KitchenSink4Word/blob/main/docs/MIGRATION_V2.md - Landing page: https://kitchensink4ai.github.io/KitchenSink4Word/ - Issues, including licensing: https://github.com/KitchenSink4AI/KitchenSink4Word/issues/new/choose ## 10. License AGPL-3.0. Free for individuals and personal use. A company building this into a 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 ## 11. 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.