# Vespper

> Vespper is a DOCX MCP Server for AI agents that need to read, search, and edit existing Word documents. Agents work with HTML; Vespper applies edits to the DOCX. New edits are tracked by default, with a configurable tracking preference.

The hosted service uses document sessions. Upload a DOCX once, attach the session ID to tool calls, retrieve the updated document, and close the session. The tools include read_document, search_document, and edit_document. A Vespper API key and the agent's model-provider configuration are required.

A local MCP server, vespper-mcp, lets AI assistants such as Claude Code, Claude Desktop, Cursor, Codex and ChatGPT read and edit .docx files in directories you allow. Live editing streams an agent's edits into a document open in Word, ONLYOFFICE, or another editor, either applied directly or proposed as suggestions the user accepts.

These reference guides are published separately from the product blog. Each Markdown guide has a canonical HTML page containing the same guidance. Tool schemas and implementation details are maintained in the official API documentation.

## Start here: build a DOCX editing agent

Follow this path from choosing tools to delivering changes a person can review, or jump to the topic that matches your current task.

1. [Choose your tools](https://www.vespper.com/llms/docx-libraries-for-agents.md): Match libraries and MCP servers to the document workflow you need to build.
2. [Build an editing agent](https://www.vespper.com/llms/build-docx-editing-agent.md): Connect document tools, manage a session, and deliver the updated DOCX.
3. [Preserve formatting](https://www.vespper.com/llms/preserve-docx-formatting.md): Scope the edit and check surrounding text, tables, images, and document structure.
4. [Return changes for review](https://www.vespper.com/llms/tracked-changes-api.md): Run a contract edit and inspect the native revisions and preservation checks.

## Choosing DOCX tools

Start with the document your application needs to deliver. Compare libraries, converters, and MCP servers by whether you need to generate a file, extract content, or edit an existing document.

Start with: [DOCX libraries for AI agents: choose by editing workflow](https://www.vespper.com/llms/docx-libraries-for-agents.md).

- [DOCX libraries for AI agents: choose by editing workflow](https://www.vespper.com/llms/docx-libraries-for-agents.md): Which DOCX library or editing API should I use for an AI agent? Compare Python DOCX editing, JavaScript generation, templates, HTML conversion, and Vespper MCP based on the document task your agent must perform.

## Agent and editor integration

Connect document tools to your application and return the edited file to the user. Start with the session lifecycle, then use the Office.js example if your agent needs to work inside Word.

Start with: [Build an AI agent that edits existing DOCX documents](https://www.vespper.com/llms/build-docx-editing-agent.md).

- [Build an AI agent that edits existing DOCX documents](https://www.vespper.com/llms/build-docx-editing-agent.md): How do I build an AI agent that edits an existing DOCX file? Connect a document-editing agent to Vespper DOCX MCP: open a session, read or search, apply targeted edits, save the document, and close the session.
- [Build an AI Word add-in with Office.js and Vespper](https://www.vespper.com/llms/build-ai-word-add-in.md): How do I build an AI Word add-in with Vespper? Build a Word add-in with Office.js, React, and Vespper DOCX MCP. Run our open-source example, stream AI edits into Word, and review tracked changes.

## Editing existing documents

Locate the right passage, make a targeted change, and check what survives the edit. These guides cover formatting, ambiguous matches, and finding content in long documents.

Start with: [Preserving DOCX formatting when an AI agent edits a file](https://www.vespper.com/llms/preserve-docx-formatting.md).

- [Find and edit a passage in a large DOCX document](https://www.vespper.com/llms/search-large-documents.md): How do I find and edit a passage in a long DOCX without reading the whole file? Use document search, page ranges, unique HTML anchors, and revision checks to target edits in long Word files without loading the whole file into an agent.
- [Preserving DOCX formatting when an AI agent edits a file](https://www.vespper.com/llms/preserve-docx-formatting.md): How can an AI edit a Word document without losing its formatting? Understand run formatting, targeted HTML edits, document structure, and practical checks for preserving an uploaded DOCX during agent-driven editing.

## Review and validation

Return edits as native Word tracked changes so a person can review them. Use a sample contract, recorded API outputs, and verification code to inspect the result and understand the checks' limits.

Start with: [DOCX tracked changes API: redline a contract with an agent](https://www.vespper.com/llms/tracked-changes-api.md).

- [DOCX tracked changes API: redline a contract with an agent](https://www.vespper.com/llms/tracked-changes-api.md): How do I return AI edits as native Word tracked changes? Return agent edits as native Word tracked changes. Run a Python contract-editing example with a sample DOCX, revision authors, and preservation checks.

## Python DOCX troubleshooting

Use Python for document changes your application can specify directly. Work through text split across runs, table cells, missing images, and review comments before connecting those operations to an agent.

Start with: [python-docx: create and edit Word documents in Python](https://www.vespper.com/llms/python-docx.md).

- [Add review comments to DOCX with python-docx](https://www.vespper.com/llms/python-docx-comments.md): How do I add a comment to a sentence in a Word document using Python? Use python-docx 1.2.0 to anchor a review comment to runs. Understand sentence boundaries, comment authors, and the difference between comments and tracked edits.
- [Find and replace text in DOCX tables with Python](https://www.vespper.com/llms/python-docx-replace-in-tables.md): Why does my python-docx find-and-replace skip text inside tables? Find text in table-cell paragraphs, including nested tables, without treating merged cells as separate values or overwriting the whole cell.
- [python-docx: create and edit Word documents in Python](https://www.vespper.com/llms/python-docx.md): How do I create and edit Word documents with Python? Install python-docx, read and edit existing Word files, and replace text while keeping run formatting. Runnable examples, comments, and tracked-change limits.
- [Replace text split across runs in python-docx](https://www.vespper.com/llms/python-docx-replace-across-runs.md): How do I replace text in a DOCX when the phrase is split across runs? Replace a phrase that spans multiple Word runs without flattening the paragraph. Decide how replacement text inherits formatting and handle ambiguous matches.
- [Why images disappear after python-docx text replacement](https://www.vespper.com/llms/python-docx-preserve-images.md): Why did images disappear after I replaced text with python-docx? Avoid removing inline drawings when changing DOCX text. Inspect run content, skip unmatched runs, and verify images before and after the edit.

## Choosing an integration

- [DOCX MCP servers compared](https://www.vespper.com/compare/docx-mcp-servers): Compare documented deployment, document handling, and review output, with links to official sources and Vespper's benchmark results for the listed tested versions.

## Integration documentation

- [Quickstart](https://docs.vespper.com/quickstart.md): Python and TypeScript integrations, including SDK and manual wiring.
- [API and sessions](https://docs.vespper.com/primitives/overview.md): Endpoints, authentication, session lifecycle, and MCP metadata.
- [Read document](https://docs.vespper.com/primitives/read-document.md): Page ranges and current HTML.
- [Search document](https://docs.vespper.com/primitives/search-document.md): Patterns, pagination, and complete edit anchors.
- [Edit document](https://docs.vespper.com/primitives/edit-document.md): Edit scope, tracking, batching, and recovery from partial results.
- [AI assistants](https://docs.vespper.com/ai-assistants.md): Connect Claude Code, Cursor, Codex, or another local MCP client with the vespper-mcp server.
- [Live editing](https://docs.vespper.com/live-editing/introduction.md): Stream an agent's edits into a document open in Word, ONLYOFFICE, or another editor.
- [Suggestions](https://docs.vespper.com/live-editing/suggestions.md): Propose edits for the user to review before they change the document.
- [Cookbooks](https://docs.vespper.com/cookbooks/overview.md): Word add-in, ONLYOFFICE add-in, and EigenPal docx-editor examples.
- [Documentation index](https://docs.vespper.com/llms.txt): Complete documentation navigation.

## Optional

- [All reference guides in one file](https://www.vespper.com/llms-full.txt): Expanded Markdown content for clients that need the full collection.
- [Guide index](https://www.vespper.com/guides): Human-readable navigation to the same reference collection.
- [Agent integration notes](https://www.vespper.com/skills.md): Concise session-based integration instructions.
- [Open-source examples](https://github.com/vespperhq/examples): Example applications maintained by Vespper.
- [Security](https://www.vespper.com/security): Published security information.
- [Pricing](https://www.vespper.com/pricing): Current plans and pricing.