# docx-mcp

A Node.js MCP server that lets clients create, query, edit, and save DOCX documents using a JSON schema, powered by the `docx` library.

## Features
- **Complete DOCX operations**: Create, edit, and save Word documents via Model Context Protocol (MCP)
- **JSON Schema validation**: Structured document definition with comprehensive validation
- **Rich content blocks**:
  - **Text & Headings**: 6 heading levels with advanced formatting
  - **Lists**: Ordered/unordered lists with multiple numbering styles and nesting
  - **Code Blocks**: Syntax highlighting for 180+ languages with themes and line numbers
  - **Tables**: Full table support with styling and cell formatting
  - **Images**: URL downloads with fallback, local files, and base64 embedding
  - **Page Control**: Page breaks and section breaks
- **Advanced text formatting**:
  - Basic: Bold, italic, underline, strikethrough, colors
  - Enhanced: Superscript, subscript, font families, highlights, small caps
  - Spacing: Character spacing, paragraph alignment, indentation
- **Document management**: In-memory registry with unique IDs
- **Metadata support**: Complete document properties and custom metadata
- **File operations**: Open existing DOCX files and save to disk
- **Error handling**: Graceful fallbacks and comprehensive validation

## JSON Schema
See `src/schema.ts` for the full schema. Key concepts:
- **meta**: Document metadata (title, subject, creator, etc.)
- **pageSettings**: Page size, orientation, margins, header/footer margins (NEW in v0.3.0)
- **headers**: Page header configuration with default/first/even page support (NEW in v0.4.0)
- **footers**: Page footer configuration with default/first/even page support (NEW in v0.4.0)
- **content**: Array of blocks: heading, paragraph, table, image, codeBlock, list, pageBreak, horizontalRule, blockquote, infoBox, textBox
- **Enhanced blocks**:
  - **CodeBlock**: `{ type: "codeBlock", language: "javascript", code: "...", showLineNumbers: true }`
  - **List**: `{ type: "list", ordered: true, items: [...] }` with nesting support
  - **Table**: Enhanced with backgroundColor, borders, verticalAlign, cell margins (NEW in v0.3.0)
  - **HorizontalRule**: `{ type: "horizontalRule", style: "single", color: "#666" }` (NEW in v0.3.0)
  - **Blockquote**: `{ type: "blockquote", children: [...], borderColor: "#ccc" }` (NEW in v0.3.0)
  - **InfoBox**: `{ type: "infoBox", boxType: "info", title: "Note", children: [...] }` (NEW in v0.3.0)
  - **TextBox**: `{ type: "textBox", children: [...] }` with border styling (NEW in v0.3.0)
  - **Enhanced TextRun**: Supports fontFamily, superScript, subScript, highlight, etc.
- Each paragraph/heading uses inline runs (text, hyperlink) with rich formatting options

### Headers & Footers Configuration (NEW in v0.4.0)
```json
{
  "headers": {
    "default": {
      "alignment": "center",
      "children": [
        {
          "type": "documentTitle",
          "bold": true,
          "size": 14,
          "color": "#1f4788"
        }
      ]
    },
    "first": {
      "alignment": "right",
      "children": [
        {
          "type": "text",
          "text": "Confidential Document",
          "bold": true,
          "color": "#cc0000"
        }
      ]
    }
  },
  "footers": {
    "default": {
      "alignment": "center", 
      "children": [
        {
          "type": "text",
          "text": "Page "
        },
        {
          "type": "pageNumber",
          "format": "decimal"
        },
        {
          "type": "text",
          "text": " of "
        },
        {
          "type": "pageNumber",
          "format": "totalPages"
        }
      ]
    }
  }
}
```

Supported header/footer elements:
- **text**: Static text with styling options
- **pageNumber**: Auto page numbering (decimal, upperRoman, lowerRoman, upperLetter, lowerLetter)
- **currentDate**: Auto-updating date with custom format strings
- **documentTitle**: References document meta.title
- **image**: Images in headers/footers (base64, path, url)

## New in v0.4.0 - Document Structure & Headers/Footers
- ✅ **Headers & Footers System**: Comprehensive page header and footer support
  - Default, first page, and even page headers/footers
  - Rich content: text, page numbers, dates, document title, images
  - Flexible alignment: left, center, right
  - Advanced styling: fonts, colors, sizes, bold/italic
- ✅ **Dynamic Content Elements**:
  - `pageNumber`: Automatic page numbering with multiple formats (decimal, roman, letters)
  - `currentDate`: Auto-updating dates with custom formats
  - `documentTitle`: Reference document metadata
  - `text`: Static text with full styling options
  - `image`: Headers/footers images support
- ✅ **Professional Layout Control**:
  - Different headers/footers for first page vs. rest of document
  - Odd/even page variations for book-style layouts
  - Precise margin control for headers and footers
  - Integration with existing page settings system

## New in v0.3.0 - Styles & Layout
- ✅ **Page Settings**: Page size (A4, Letter, etc.), orientation, margins control
- ✅ **Enhanced Tables**: Background colors, border styles, vertical alignment, table templates
- ✅ **New Block Types**: Horizontal rules, blockquotes, info boxes, text boxes
- ✅ **Advanced Styling**: More comprehensive table and cell formatting options

## Previous Updates
### v0.2.0 - Enhanced Document Operations
- ✅ **Code Blocks**: Syntax highlighting for 180+ programming languages
- ✅ **Lists**: Ordered and unordered lists with multiple styles and nesting
- ✅ **Page Breaks**: Control document pagination
- ✅ **Enhanced Text**: Superscript, subscript, font families, highlights
- ✅ **Improved Schema**: More comprehensive validation and type safety

## Run locally
1. Install deps

```pwsh
npm install
```

2. Dev mode

```pwsh
npm run dev
```

3. Build and start

```pwsh
npm run build
npm start
```

## Tools
- docx-getSchema { } // Get JSON schema - call this first!
- docx-create { json }
- docx-open { id?, path }  // open .docx file from disk
- docx-queryMeta { id }
- docx-queryObjects { id }
- docx-editMeta { id, patch }
- docx-editContent { id, index, block }
- docx-insertContent { id, index, block }
- docx-removeContent { id, index }
- docx-save { id, path }
- docx-exportJson { id }

## Example JSON
```json
{
  "meta": { "title": "Demo", "creator": "DOCX MCP v0.2.0" },
  "content": [
    { "type": "heading", "level": 1, "children": [ { "type": "text", "text": "Title" } ] },
    { "type": "paragraph", "children": [ 
      { "type": "text", "text": "Hello ", "bold": true }, 
      { "type": "text", "text": "world", "color": "FF0000" } 
    ]},
    { 
      "type": "codeBlock", 
      "language": "javascript", 
      "showLineNumbers": true,
      "code": "console.log('Hello, World!');" 
    },
    {
      "type": "list",
      "ordered": false,
      "items": [
        { "children": [{ "type": "text", "text": "First item" }] },
        { "children": [{ "type": "text", "text": "Second item" }] }
      ]
    },
    { "type": "image", "url": "https://picsum.photos/300/200", "width": 300, "height": 200 },
    { "type": "pageBreak" },
    { "type": "table", "rows": [ { "cells": [ 
      { "children": [ { "type": "paragraph", "children": [ { "type": "text", "text": "A" } ] } ] }, 
      { "children": [ { "type": "paragraph", "children": [ { "type": "text", "text": "B" } ] } ] } 
    ] } ] }
  ]
}
```

## Image Support
Images can be included in three ways:
- **URL**: `{ "type": "image", "url": "https://example.com/image.png", "width": 300, "height": 200 }`
- **Local file path**: `{ "type": "image", "path": "/path/to/image.png", "width": 300, "height": 200 }`
- **Base64 data**: `{ "type": "image", "data": "base64string", "format": "png", "width": 150, "height": 100 }`

**URL Image Features:**
- Automatic download from HTTP/HTTPS URLs
- Fallback to generated placeholder image if download fails
- Placeholder shows original URL and dimensions
- Support for common image formats (PNG, JPEG, JPG)
- Note: Fontconfig warnings on Windows are harmless and can be ignored

Supported formats: PNG, JPEG, JPG

## Notes
- Hyperlinks are rendered visually as underlined blue text. Full hyperlink relationships can be added later.
- Images support URL downloads, local file paths, and base64 data.
- This server runs over stdio to be compatible with MCP hosts.