한국어 | English

udfp — Universal Document Format Protocol

Parse, transform, and render HWP/HWPX/DOCX/PDF/MD documents through a unified Document Model.

UDF (Universal Document Format) is the format — a unified document model that normalizes heterogeneous file formats into a common block tree. UDFP (Universal Document Format Protocol) is the protocol layer — an MCP server that lets AI agents read, edit, and generate documents through UDF.

pip install udfp installs both:

• udf — Core library. Parsers, renderers, Document Model, validation, CLI.
• udfp — MCP server. Exposes udf to Claude and other LLM agents via the Model Context Protocol.

pip install udfp        →  import udf       (library)
pip install udfp[mcp]   →  udfp             (MCP server)

Features

• Multi-format parsing — HWP (binary), HWPX (OOXML-like ZIP), DOCX, PDF, Markdown, HTML, XML
• Lossless round-trip — HWP/HWPX/DOCX same-format conversions preserve content via verbatim layer
• Cross-format conversion — Convert between supported format pairs (e.g., HWP → DOCX, PDF → MD)
• Programmatic editing — Add, modify, or remove blocks/inlines via UdfDocument API
• Two generation modes — Seed Patch (modify in-place) and From Scratch (full regeneration)
• Structural validation — R-rules for HWP (R1–R4), HX-rules for HWPX (HX1–HX4), D-rules for DOCX (D1–D3) — all implemented
• MCP server — Claude/LLM integration for reading, editing, and generating documents

Installation

pip install udfp

With MCP server:

pip install udfp[mcp]

For development:

pip install udfp[dev]

udf — Core Library

Parse a document

import udf

doc = udf.parse("report.hwp")
print(f"{len(doc.blocks)} blocks parsed")

Convert between formats

import udf

udf.convert("input.hwp", "output.docx")
udf.convert("paper.pdf", "paper.md")

Programmatic editing

import udf
from udf.schema.blocks import ParagraphBlock
from udf.schema.inlines import TextInline

doc = udf.parse("template.hwp")

doc.replace_text("PLACEHOLDER", "Actual Value")

new_block = ParagraphBlock(
    type="paragraph",
    id="new-1",
    inlines=[TextInline(type="text", text="New content")],
)
doc.add_block(new_block)

udf.render(doc, "hwp", output_path="filled.hwp")

CLI

udf convert input.hwp -o output.docx
udf inspect document.hwp
udf validate document.hwp
udf diff original.hwp modified.hwp

udfp — MCP Server

The MCP server lets LLMs read, edit, and generate documents through tool calls.

Start the server

udfp                                          # stdio (default)
udfp --transport streamable-http --port 8000  # HTTP

Available tools

Claude Desktop config

{
  "mcpServers": {
    "udfp": {
      "command": "udfp"
    }
  }
}

Document Model

All formats are normalized into a common block tree:

Generation Modes

Seed Patch (default when original exists)

Preserves the original binary/ZIP, replacing only modified streams. Guarantees bit-perfect preservation of unmodified regions.

Best for: Form filling, text replacement, content updates without structural changes.

From Scratch (automatic fallback)

Regenerates the entire output file from the Document Model. Required when blocks are added, removed, or restructured.

Automatic detection: If any block lacks a verbatim_ref (i.e., was programmatically added), the renderer automatically falls back to From Scratch mode.

Supported Formats

Cross-format Conversion Matrix

• Lossless: Verbatim layer preserves all binary content (Seed Patch mode)
• Semantic: Block structure and text preserved; format-specific styling may differ (From Scratch mode)
• Text-level: Text content preserved; formatting, page layout, images lost
• From Scratch: Generates new binary from Document Model; requires original for best results

Known Limitations

From Scratch mode (used for cross-format and structural edits):

• DrawingBlock, ChartBlock, TextArtBlock cannot be regenerated without the original file — reported as FORMAT_LIMIT loss
• Complex table structures (merged cells, nested tables) may not fully survive HWPX/DOCX → HWP conversion

Validation rules:

• HWP: R1–R4 structural rules + I1–I3 integrity checks — fully implemented with auto-fixers
• HWPX: HX1–HX4 structural rules — fully implemented
• DOCX: D1–D3 structural rules — fully implemented
• PDF: format-specific rules planned (not needed until PDF rendering is added)

Text-level formats (MD, HTML):

• Formatting (fonts, colors, margins), images, and page layout are not preserved
• Useful for text extraction and content editing, not visual fidelity

Architecture

Input File ──▶ Parser ──▶ UdfDocument ──▶ Renderer ──▶ Output File
                              │
                              ▼
                     Document Model (blocks/inlines)
                              +
                     Verbatim Layer (binary preservation)
                              +
                     Loss Report (what was dropped)

Development

pytest                        # all tests
pytest tests/roundtrip/       # round-trip tests
pytest tests/validation/      # R-rule validation
ruff check . && ruff format . # lint + format
mypy udf/                     # type check

License

Business Source License 1.1 (BUSL-1.1) — see LICENSE and NOTICE.

Non-commercial, academic, and personal use is free. For commercial or production use, contact h000000nkim@gmail.com.