DraftAgent

DraftAgent MCP Server for DOCX Automation

DraftAgent is a local Model Context Protocol server for AI-powered DOCX automation. It lets MCP-compatible clients inspect Word documents, apply structured transformations, and render DOCX files as DOCX, HTML, or PDF artifacts.

For installation and general setup, see the DraftAgent documentation. This page describes the MCP tools, request contract, and supported document operations.

Compatibility note: DraftAgent may not preserve all formatting or document features during transformations. Validate results with your documents before relying on them in production workflows.

Status: Active development. Tool schemas, operation support, response shapes, limits, and resource contents may change. Query tools/list and capabilities at runtime instead of hard-coding the operation catalog.

The current public MCP schema version is 1. It is returned as schemaVersion by capabilities and the capability resources. The DraftAgent package/server version is separate and may change without changing the MCP contract.

Quick start

The server communicates over MCP JSON-RPC on standard input and output. Logs are written to stderr; stdout is reserved for protocol traffic.

Set the workspace directory before starting the server:

export DRAFTAGENT_DOCUMENTS_DIRECTORY=/path/to/documents
draftagent-mcp

The workspace must exist and is canonicalized at startup. Tool paths are relative to this directory. Absolute paths, parent traversal, and symlinks are rejected.

Tools

The current server registers six tools. Request and response schemas are available at runtime through capabilities.

list_files

Read-only workspace file listing. It does not return file contents.

  • recursive traverses directories when true.
  • extension filters by file extension.
  • Each entry includes filename, byte size, modification time, and inferred contentType.
  • A response is limited to 10,000 files.

document_inspect

Loads a workspace-relative DOCX and returns package statistics, core metadata, and a session-scoped document handle.

  • detail accepts outline, text, or full.
  • elements: true includes model elements.
  • filter.kinds, pathPrefix, textContains, tableIndex, and sectionIndex filter elements.
  • offset and limit paginate element output.
  • Text and full detail include an ordered text projection with Unicode-scalar offsets.
  • Element IDs and revisions are scoped to the current session.

document_convert

Loads a DOCX and writes a rendered artifact to outputFile. Supported format values are docx, html, and pdf.

The response includes artifact filename, size, content type, URI, and renderer warnings. An optional title is used during rendering.

document_transform

Applies a non-empty, ordered operations array and writes the result to outputFile.

Provide either:

  • inputFile to load a workspace document or reuse its latest session; or
  • document with documentId and revision to address an inspected session.

Output defaults to DOCX. Set output.format to docx, html, or pdf. Writes use a temporary file followed by rename. Existing document handles must use the latest revision; stale revisions return STALE_REVISION.

capabilities

Returns the server and schema versions, supported formats, ZIP and response limits, inspection conventions, error conventions, resources, and the complete transformation operation catalog with schemas and examples.

read_capability_resource

Reads a capability resource through a tool call for MCP hosts that do not expose resource methods. Supported URIs are:

  • draftagent://capabilities
  • draftagent://transforms

Transformation operations

Transformation requests are modeled as an ordered, transactional operations array. Each operation has an op ID and operation-specific fields. The canonical operation inventory is used to generate tools/list, the capabilities catalog, and the draftagent://transforms resource.

The following 40 operation IDs are currently supported:

Text and structural blocks

  • replaceText replaces matching text in runs. Its required fields are search and replaceWith; all controls whether every match is replaced (default true). Text split across separate DOCX runs is not matched as one string.
  • replaceElementText replaces the content of one paragraph identified by a target.
  • appendParagraph adds a paragraph to the end of the document. Supply non-empty text or paragraph content.
  • insertParagraph inserts a paragraph before or after a target block.
  • insertBlocks inserts model block inputs at a target position.
  • deleteBlock, moveBlock, and cloneBlock delete, move, or clone a block. Moved blocks retain their IDs; cloned blocks receive fresh IDs.
  • replaceBlock replaces a block with supplied blocks, and replaceBlockRange replaces an inclusive block range.
  • replaceParagraphContent replaces a paragraph's runs while preserving the paragraph's element ID.

Formatting

  • setHeadingLevel sets a paragraph heading level from 1 through 9.
  • setRunFormat sets run styling; applyRunFormat applies a partial patch; removeRunFormat clears selected fields.
  • setParagraphStyle sets paragraph styling; applyParagraphFormat applies a partial patch; removeParagraphFormat clears selected fields.
  • setRunStyle sets run styling using the same run-style properties.

Run formatting includes font family, size, color, bold, italic, underline, and strike. Paragraph formatting includes alignment, spacing, indentation, and related paragraph properties. Formatting targets support batches of IDs or paths, and run formatting can also select every matching run by text. Unspecified properties in an apply patch are preserved; use an explicit remove operation to clear a property. setRunFormat is the canonical MCP ID; internal Rust names such as apply_run_format are not MCP operation IDs.

Lists

  • applyList converts paragraphs to bulleted or numbered lists.
  • setListLevel changes list nesting level, starting at 0, and removeList removes list formatting.
  • insertListItem, moveListItem, and deleteListItem insert, move, or delete list items.

Tables

  • addTable, deleteTable, and moveTable insert, delete, or move tables.
  • addRow, insertRow, and deleteRow modify table rows.
  • addColumn, insertColumn, and deleteColumn modify table columns. Column positions are zero-based.
  • setCellText replaces cell text, while replaceCellContent replaces cell blocks.
  • mergeCells merges an inclusive rectangular table range, and splitCell splits a merged cell.
  • setRowShading and setCellShading set or remove shading. Shading fills use six-digit RGB hexadecimal colors, with an optional pattern.

Table mutations validate grid geometry and report INVALID_TABLE_GEOMETRY for unsupported or inconsistent ranges.

Selectors and validation

Selectors must be one of an element ID or model path string, an object containing only id, an object containing only path, or a table position containing tableIndex and optional row/column indexes. Ambiguous selectors are rejected. The server enforces these rules even when an MCP host does not fully enforce JSON Schema.

document_transform requires exactly one source: document with a session documentId and revision, or a workspace-relative inputFile. The operations array must be non-empty. IDs and revisions are session-scoped; stale revisions return STALE_REVISION. Output formats are docx, html, and pdf. Run colors use six-digit hexadecimal RGB values or auto, font sizes must be positive finite numbers, and underline values are limited to those advertised by the tool schema.

Unsupported operations from lower-level transformation crates are not included in capability discovery and must not be submitted to document_transform. There are currently no supported aliases for the public operation IDs.

Protocol contract

Resources

Resources are enabled alongside tools and expose JSON at draftagent://capabilities and draftagent://transforms. Both capability responses are generated from the canonical operation inventory.

Client compatibility

MCP hosts differ in how completely they enforce JSON Schema features such as oneOf, enum, const, and additionalProperties. Clients should:

  1. use tools/list as the invocation schema;
  2. use the canonical operation IDs returned by the schema and catalog;
  3. treat server-side validation errors as authoritative; and
  4. check schemaVersion when caching schemas or generated prompts.

Clients that cannot consume the advertised schema can still call capabilities or read the capability resources, but must not infer support for operations absent from tools/list.

Sessions and revisions

document_inspect publishes a document handle and revision. A successful transform advances the revision. Element IDs are intended for the latest session revision and should not be treated as durable document identifiers.

Errors

Invalid requests return structured codes such as INVALID_TARGET, STALE_REVISION, and TRANSFORMATION_FAILED. Transformation diagnostics include code, message, path, part, and operation.

Limits

Tool responses are capped at 2 MiB. ZIP inputs are constrained by configured entry, per-entry, and total-size limits. The active values are returned by capabilities.

Frequently asked questions

What is the DraftAgent MCP server?

DraftAgent is a local MCP server that allows AI agents and MCP clients to inspect, transform, and render DOCX documents.

Can DraftAgent modify Word documents?

Yes. DraftAgent supports text replacement, structural edits, formatting, lists, tables, shading, and other document transformations.

What output formats does DraftAgent support?

DraftAgent can produce DOCX, HTML, and PDF output artifacts.

Does DraftAgent upload documents to a remote service?

The MCP server runs locally and uses a configured workspace directory for document files.