Metadata-Version: 2.4
Name: docx-creator-mcp
Version: 0.1.0
Summary: An MCP server for creating, analyzing, and rendering professional DOCX documents programmatically.
Project-URL: Homepage, https://pypi.org/project/docx-creator-mcp/
Project-URL: Issues, https://github.com/harmandatta/docx-creator-mcp/issues
Author: Harman Datta
License-Expression: MIT
License-File: LICENSE
Keywords: document,document-generation,docx,fastmcp,mcp,model-context-protocol,word
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-docx>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: pdf
Requires-Dist: pdf2image>=1.16.0; extra == 'pdf'
Description-Content-Type: text/markdown

# docx-creator-mcp

A Model Context Protocol (MCP) server for creating, analyzing, and rendering professional Microsoft Word (DOCX) documents. Built on [FastMCP](https://github.com/jlowin/fastmcp) and [python-docx](https://python-docx.readthedocs.io/).

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [MCP Client Configuration](#mcp-client-configuration)
- [Tools Reference](#tools-reference)
  - [create_document](#create_document)
  - [analyze_document](#analyze_document)
  - [render_document_screenshots](#render_document_screenshots)
- [Block Types](#block-types)
- [Inline Styling](#inline-styling)
- [Document Style Overrides](#document-style-overrides)
- [Examples](#examples)
- [License](#license)

---

## Overview

`docx-creator-mcp` exposes three MCP tools that allow AI agents and automation pipelines to generate, inspect, and render Word documents without manual intervention. It accepts structured JSON block data and produces fully formatted `.docx` files with support for headings, paragraphs, tables, images, lists, quotes, and inline styling.

---

## Features

- **Document creation** from structured block data (headings, paragraphs, tables, images, lists, quotes, page breaks, horizontal rules).
- **Inline rich-text styling** via `<style>` tags with support for color, font size, font family, bold, italic, underline, and highlight.
- **Document analysis** that extracts page layout, metadata, paragraph-level formatting, table structure (including merged cells, nested tables, column spans), inline images, and a global style palette.
- **Page rendering** to PNG images via LibreOffice headless, Word COM (Windows), or a pure-Python fallback.
- **Image embedding** from local file paths or URLs.
- **Customizable document themes** including fonts, colors, margins, and line spacing.

---

## Requirements

- Python 3.10 or later
- For PNG rendering (optional): LibreOffice installed, or `pdf2image` with Poppler

---

## Installation

### From PyPI

```bash
pip install docx-creator-mcp
```

### With PDF rendering support

```bash
pip install docx-creator-mcp[pdf]
```

### From source

```bash
git clone https://github.com/harmandatta/docx-creator-mcp.git
cd docx-creator-mcp
pip install -e .
```

---

## Quick Start

Run the MCP server:

```bash
docx-creator-mcp
```

Or run as a Python module:

```bash
python -m docx_creator_mcp.server
```

---

## MCP Client Configuration

### Kiro

Add to `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "docx-creator": {
      "command": "docx-creator-mcp",
      "args": []
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "docx-creator": {
      "command": "docx-creator-mcp",
      "args": []
    }
  }
}
```

### Using uvx (no install required)

```json
{
  "mcpServers": {
    "docx-creator": {
      "command": "uvx",
      "args": ["docx-creator-mcp"]
    }
  }
}
```

---

## Tools Reference

### create_document

Creates a DOCX file from an ordered list of content blocks.

**Parameters:**

| Parameter        | Type          | Required | Description                                                                 |
|------------------|---------------|----------|-----------------------------------------------------------------------------|
| `blocks`         | `list[dict]`  | Yes      | Ordered list of content blocks. Each block must include a `type` field.     |
| `output_dir`     | `str`         | Yes      | Directory where the file will be saved. A `generated-docx` subdirectory is created automatically. |
| `filename`       | `str`         | No       | Output filename. Defaults to `document.docx`.                               |
| `document_style` | `dict`        | No       | Style overrides for fonts, colors, margins, and spacing.                    |
| `metadata`       | `dict`        | No       | Document metadata: `title`, `author`, `subject`.                            |

**Returns:** Absolute path to the generated DOCX file.

---

### analyze_document

Extracts the complete structure and styling from an existing DOCX file.

**Parameters:**

| Parameter   | Type  | Required | Description                          |
|-------------|-------|----------|--------------------------------------|
| `docx_path` | `str` | Yes      | Absolute path to the DOCX file.      |

**Returns:** JSON string containing:

- `page_layout` -- Page dimensions, margins, orientation.
- `metadata` -- Title, author, creation/modification dates.
- `global_palette` -- Most-used colors, fonts, and font sizes.
- `content` -- Ordered list of paragraphs and tables with full run-level formatting.
- `styles_defined` -- All document-level styles with their properties.

---

### render_document_screenshots

Renders DOCX pages as PNG images for visual inspection.

**Parameters:**

| Parameter    | Type  | Required | Description                                                        |
|--------------|-------|----------|--------------------------------------------------------------------|
| `docx_path`  | `str` | Yes      | Absolute path to the DOCX file.                                    |
| `output_dir` | `str` | No       | Directory to save PNGs. Defaults to a `screenshots` folder next to the file. |
| `width`      | `int` | No       | Output image width in pixels. Defaults to 1600.                    |

**Returns:** JSON with a list of rendered pages, each containing `page`, `image_path`, and `backend`.

**Rendering backends** (tried in order):

1. LibreOffice headless (macOS, Linux, Windows)
2. Word COM automation (Windows only)
3. Pure-Python fallback using Pillow

---

## Block Types

Each block in the `blocks` list must include a `type` field. The following types are supported:

### heading

Section heading with configurable level.

```json
{ "type": "heading", "text": "Quarterly Report", "level": 1 }
```

| Field   | Type  | Default | Description            |
|---------|-------|---------|------------------------|
| `text`  | `str` | --      | Heading text. Supports inline `<style>` tags. |
| `level` | `int` | 1       | Heading level, 1 through 4. |

### paragraph

Body text with optional alignment.

```json
{ "type": "paragraph", "text": "Revenue increased by 12%.", "alignment": "justify" }
```

| Field       | Type  | Default  | Description                                      |
|-------------|-------|----------|--------------------------------------------------|
| `text`      | `str` | --       | Paragraph text. Supports inline `<style>` tags.  |
| `alignment` | `str` | `"left"` | One of `left`, `center`, `right`, `justify`.     |

### bullet_list

Bulleted list.

```json
{ "type": "bullet_list", "items": ["First item", "Second item", "Third item"] }
```

| Field   | Type         | Description                                    |
|---------|--------------|------------------------------------------------|
| `items` | `list[str]`  | List of bullet items. Each supports `<style>` tags. |

### numbered_list

Numbered list.

```json
{ "type": "numbered_list", "items": ["Step one", "Step two", "Step three"] }
```

| Field   | Type         | Description                                      |
|---------|--------------|--------------------------------------------------|
| `items` | `list[str]`  | List of numbered items. Each supports `<style>` tags. |

### table

Data table with optional header styling and row striping.

```json
{
  "type": "table",
  "headers": ["Name", "Department", "Salary"],
  "rows": [
    ["Alice", "Engineering", "120000"],
    ["Bob", "Marketing", "95000"]
  ],
  "stripe_rows": true
}
```

| Field             | Type            | Default       | Description                                  |
|-------------------|-----------------|---------------|----------------------------------------------|
| `headers`         | `list[str]`     | --            | Column header labels.                        |
| `rows`            | `list[list]`    | --            | Row data. Each inner list is one row.        |
| `header_bg_color` | `str`           | Accent color  | Hex color for the header row background.     |
| `stripe_rows`     | `bool`          | `true`        | Alternate row shading for readability.       |

### image

Inline image from a local path or URL.

```json
{
  "type": "image",
  "image_path": "/path/to/screenshot.png",
  "width_inches": 5.5,
  "caption": "Figure 1: Application dashboard"
}
```

| Field          | Type    | Default | Description                              |
|----------------|---------|---------|------------------------------------------|
| `image_path`   | `str`   | --      | Local file path or HTTP/HTTPS URL.       |
| `width_inches` | `float` | 5.5     | Display width in inches.                 |
| `caption`      | `str`   | --      | Optional caption rendered below the image. |

### quote

Block quote with attribution.

```json
{
  "type": "quote",
  "text": "Simplicity is the ultimate sophistication.",
  "attribution": "-- Leonardo da Vinci"
}
```

| Field         | Type  | Description                                  |
|---------------|-------|----------------------------------------------|
| `text`        | `str` | Quote text. Supports inline `<style>` tags.  |
| `attribution` | `str` | Source attribution rendered below the quote.  |

### page_break

Forces a new page.

```json
{ "type": "page_break" }
```

### horizontal_rule

Inserts a horizontal divider line.

```json
{ "type": "horizontal_rule" }
```

---

## Inline Styling

Any text field in any block type supports inline `<style>` tags for granular formatting control.

**Syntax:**

```
Regular text <style color="green" bold="true" text-size="14">highlighted text</style> more text.
```

**Supported attributes:**

| Attribute   | Type     | Description                                                                 |
|-------------|----------|-----------------------------------------------------------------------------|
| `color`     | `str`    | CSS color name (`red`, `green`, `blue`, `orange`, `accent`, `muted`) or hex (`#FF5733`). |
| `text-size` | `number` | Font size in points.                                                        |
| `font-type` | `str`    | Font family name (e.g., `Arial`, `Calibri`).                                |
| `bold`      | `bool`   | `true` or `false`.                                                          |
| `italic`    | `bool`   | `true` or `false`.                                                          |
| `underline` | `bool`   | `true` or `false`.                                                          |
| `highlight` | `str`    | Highlight color: `yellow`, `green`, `cyan`, `pink`, `red`, `blue`, `gray`.  |

**Named colors:**

`white`, `black`, `red`, `green`, `blue`, `orange`, `yellow`, `purple`, `cyan`, `gray`, `darkgray`, `navy`, `accent`, `muted`

---

## Document Style Overrides

Pass a `document_style` dictionary to `create_document` to override the default theme.

| Key                  | Type    | Default      | Description                    |
|----------------------|---------|--------------|--------------------------------|
| `font_body`          | `str`   | `Calibri`    | Body text font family.         |
| `font_heading`       | `str`   | `Calibri`    | Heading font family.           |
| `font_size_body`     | `int`   | `11`         | Body font size in points.      |
| `font_size_h1`       | `int`   | `24`         | Heading 1 font size.           |
| `font_size_h2`       | `int`   | `18`         | Heading 2 font size.           |
| `font_size_h3`       | `int`   | `14`         | Heading 3 font size.           |
| `font_size_h4`       | `int`   | `12`         | Heading 4 font size.           |
| `color_body`         | `str`   | `333333`     | Body text color (hex).         |
| `color_heading`      | `str`   | `1A1A2E`     | Heading color (hex).           |
| `color_accent`       | `str`   | `4F81BD`     | Accent color for tables (hex). |
| `line_spacing`       | `float` | `1.15`       | Line spacing multiplier.       |
| `page_margin_inches` | `float` | `1.0`        | Page margins in inches.        |

---

## Examples

### Minimal document

```json
{
  "blocks": [
    { "type": "heading", "text": "Meeting Notes", "level": 1 },
    { "type": "paragraph", "text": "Discussed Q2 targets and resource allocation." },
    { "type": "bullet_list", "items": ["Hire two engineers", "Finalize budget", "Launch beta"] }
  ],
  "output_dir": "/tmp",
  "filename": "meeting_notes.docx"
}
```

### Report with table and image

```json
{
  "blocks": [
    { "type": "heading", "text": "Sales Report", "level": 1 },
    {
      "type": "table",
      "headers": ["Region", "Q1", "Q2", "Q3"],
      "rows": [
        ["North", "1.2M", "1.4M", "1.5M"],
        ["South", "0.9M", "1.1M", "1.3M"]
      ]
    },
    {
      "type": "image",
      "image_path": "/path/to/chart.png",
      "width_inches": 6,
      "caption": "Figure 1: Quarterly revenue by region"
    },
    {
      "type": "paragraph",
      "text": "Total revenue grew <style color=\"green\" bold=\"true\">18%</style> year-over-year."
    }
  ],
  "output_dir": "/tmp",
  "filename": "sales_report.docx",
  "metadata": { "title": "Q3 Sales Report", "author": "Finance Team" }
}
```

### Custom styling

```json
{
  "blocks": [
    { "type": "heading", "text": "Brand Guidelines", "level": 1 },
    { "type": "paragraph", "text": "All documents must use the corporate font and color scheme." }
  ],
  "output_dir": "/tmp",
  "document_style": {
    "font_body": "Georgia",
    "font_heading": "Georgia",
    "color_accent": "2E86AB",
    "page_margin_inches": 1.25
  }
}
```

---

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
