DOCX MCP Server

Servidor universal de procesamiento de DOCX que implementa el Protocolo de Contexto de Modelo (MCP) con soporte completo de OOXML.

Características

• Soporte completo de OOXML: Lee/escribe todas las partes del documento DOCX (document.xml, estilos, numeración, encabezados/pies de página, etc.)

• Operaciones de texto: Extrae, busca y reemplaza texto con modos literales o de expresiones regulares

• Edición de tablas: Inserta/elimina filas y columnas, combina celdas, establece contenido de celdas

• Etiquetas de datos estructurados (SDT): Obtiene/establece controles de contenido por etiqueta o alias

• Imágenes: Lista imágenes, inserta imágenes en línea o ancladas con control de posición/tamaño

• Comentarios y cambios: Lista comentarios, agrega/elimina comentarios, acepta todos los cambios controlados

• Propiedades del documento: Lee/escribe metadatos (título, autor, asunto, etc.)

• Caché LRU: Caché eficiente en memoria de las partes del documento

• Transporte Stdio: Comunicación MCP a través de stdin/stdout

Instalación

npm install
npm run build

Ejecución

Desarrollo

npm run dev

Producción

npm start

Con Claude Code

claude mcp add --scope user --transport stdio docx -- node /path/to/dist/index.js

Herramientas

Gestión de documentos

docx.open

Abre un documento DOCX desde archivo o base64

{
  "docId": "uuid",
  "parts": ["word/document.xml", "word/styles.xml", ...],
  "partCount": 42,
  "props": { "core": {...}, "app": {...} }
}

docx.close

Cierra y descarga un documento

docx.save

Guarda el documento en un archivo o lo devuelve como base64

Gestión de partes

docx.list_parts

Lista todas las partes del documento

docx.part_read

Lee el XML sin procesar de una parte específica

docx.part_write

Escribe/actualiza el contenido XML de una parte

Operaciones de texto

docx.get_text

Extrae todo el texto del documento

{
  "docId": "uuid",
  "scope": "document" | "headers" | "footers" | "all"
}

docx.find

Busca texto con contexto

{
  "docId": "uuid",
  "query": "search term",
  "mode": "literal" | "regex"
}

docx.replace_text

Reemplaza texto en el documento

{
  "docId": "uuid",
  "match": "old text",
  "replace": "new text",
  "mode": "literal" | "regex"
}

Tablas

docx.tables_list

Lista todas las tablas con dimensiones

{
  "tables": [
    {
      "xpath": "/w:document/w:body/w:tbl[1]",
      "rows": 3,
      "colsApprox": 4
    }
  ]
}

docx.table_edit

Modifica la estructura y el contenido de la tabla

{
  "docId": "uuid",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": {
    "kind": "setCellText",
    "row": 0,
    "col": 1,
    "text": "new value"
  }
}

Operaciones:

• setCellText(row, col, text) - Establece el contenido de la celda

• insertRow(at) - Inserta una fila en la posición

• deleteRow(at) - Elimina una fila

• insertCol(at) - Inserta una columna

• deleteCol(at) - Elimina una columna

Datos estructurados (SDT)

docx.sdt_get

Obtiene el contenido del control de contenido por etiqueta o alias

docx.sdt_put

Actualiza el control de contenido

Imágenes

docx.images_list

Lista todas las imágenes con metadatos

docx.image_add

Inserta una imagen en línea o anclada

Estilos y numeración

docx.styles_get / docx.styles_set

Lee/escribe styles.xml

docx.numbering_get / docx.numbering_set

Lee/escribe numbering.xml

Encabezados/Pies de página

docx.headers_footers_list

Lista todas las partes de encabezado/pie de página

Comentarios

docx.comments_list

Lista todos los comentarios

docx.comments_add

Agrega un nuevo comentario

docx.changes_accept_all

Acepta todos los cambios controlados en el documento

Metadatos

docx.metadata_get

Obtiene las propiedades del documento (título, autor, creado, modificado, etc.)

Escenarios de prueba

1. Lectura/Escritura básica

# Open document
docx.open: { "path": "/path/to/document.docx" }

# Get text
docx.get_text: { "docId": "returned-id" }

# Replace text
docx.replace_text: {
  "docId": "returned-id",
  "match": "old text",
  "replace": "new text"
}

# Save
docx.save: { "docId": "returned-id", "returnBase64": true }

2. Manipulación de tablas

# List tables
docx.tables_list: { "docId": "id" }

# Edit cell
docx.table_edit: {
  "docId": "id",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": { "kind": "setCellText", "row": 0, "col": 0, "text": "Hello" }
}

3. Imágenes

# List images
docx.images_list: { "docId": "id" }

4. Cambios controlados

# Accept all changes
docx.changes_accept_all: { "docId": "id" }

Arquitectura

src/
  index.ts                    # Entry point
  errors.ts                   # Error definitions
  logger.ts                   # Logging utilities
  ooxml/
    namespaces.ts            # XML namespace definitions
    emu.ts                    # EMU conversion utilities
    dom.ts                    # XML DOM utilities (xmldom + fontoxpath)
    xmlParser.ts              # fast-xml-parser wrapper
    parts.ts                  # DOCX ZIP part management
    rels.ts                   # Relationships management
    text.ts                   # Text extraction & replacement
    tables.ts                 # Table operations
    sdt.ts                    # Structured Data Tags
    drawings.ts               # Images & DrawingML
    headersFooters.ts         # Headers/Footers
    styles.ts                 # Style operations
    numbering.ts              # Numbering operations
    changes.ts                # Track changes
    comments.ts               # Comments
  store/
    types.ts                  # Type definitions
    docStore.ts               # Document store + LRU cache
  mcp/
    schemas.ts                # Tool input schemas
    tools.ts                  # Tool implementations
    server.ts                 # MCP server setup

Dependencias

• @modelcontextprotocol/sdk - Implementación de MCP

• jszip - Manejo de archivos ZIP

• fast-xml-parser - Análisis XML sin pérdida

• @xmldom/xmldom - Implementación de DOM

• fontoxpath - Consultas XPath

• diff-match-patch - Diferenciación de texto

• lru-cache - Caché eficiente en memoria

• uuid - Generación de ID de documento

Notas de rendimiento

• Se admiten documentos de hasta 10 MB

• Caché LRU con límite de 100 partes y límite de memoria de 1 GB

• Las partes se cargan bajo demanda, no completamente en memoria

• Optimización de partes sucias: solo las partes modificadas se guardan en el ZIP

• Sin copia profunda de estructuras XML

Limitaciones

• Encabezados/pies de página: soporte básico (las estructuras de secciones complejas pueden requerir ajuste manual)

• Comentarios: lista/agregar/eliminar básico (las cadenas de respuestas no se admiten completamente)

• Cambios controlados: aceptar todo disponible; inspección detallada de cambios limitada

• Estilos: obtener/establecer XML completo; sin fusión selectiva de estilos

• EMU/tamaño: calculado pero la geometría renderizada depende del motor de diseño de Word

Licencia

MIT