sadt-mcp
Provides conversion and projection to/from HTML5 as one of the supported document formats, enabling multi-format document transformations involving HTML files.
Supports LaTeX as part of its 3-way equation AST compiler, translating mathematical expressions between LaTeX, Word OMML, and Hancom HWP EQN formats.
Provides conversion and projection to/from Markdown as one of the supported document formats, enabling document transformations involving Markdown files.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
SADT (Stella Actuation Document Transfer) — HWP · HWPX · DOCX Document MCP Server
[last patch : 2026-11-16 07:43:00 UTC]
🌐 English (./README.md) | 🇰🇷 한국어 (./README_KO.md) | 🤖 Agent Summary (./llms.txt) | 📋 MCP Manifest (./server.json) | 🌐 Official Showcase Hub
Active Open-Source Release (v4.1.0) — Capabilities & Current Scope
SADT (powered by the T-DIR Topological Document Intermediate Representation engine) is under active development. All 8 target formats (.hwp, .hwpx, .docx, .xlsx, .html, .pdf, .md, .csv), standalone .hwpx packaging, 3-Way Equation AST conversion, defensive archive validation ([SEC-01] ~ [SEC-06]), and 14 parametric regression cohorts (EXP-01 ~ EXP-14) pass in our test suite. However, highly customized legacy macros, encrypted DRM files, or complex free-form vector objects may still require manual review after conversion.
1. What SADT Does (In 30 Seconds)
SADT (Stella Actuation Document Transfer) is a zero-dependency Python MCP server and multi-format document engine built for Korean .hwp (v5.0 binary), .hwpx (OWPML), MS Word (.docx), Excel (.xlsx), HTML5 (.html), PDF 1.4 (.pdf), Markdown (.md), and CSV/TSV transformations without requiring Hancom Office or LibreOffice.
Common Problems It Solves
"How do I parse or generate Korean
.hwp/.hwpxfiles in Python without installing Hancom Office?"
SADT includes a pure-Python MS-CFB OLE2 reader/writer (./cfb_ole2.py) and HWP v5.0 / OWPML codecs (./codec_hwp_v5.py,./codec_ooxml_owpml.py) using only the Python standard library."How can an AI agent fill an official HWP government or grant form without breaking outer tables or overflowing page limits?"
Instead of dumping giant XML files into an LLM prompt, SADT scans template slots (SLOT 01..M) and2R x Cmedia grids (MEDIA 01..P) dynamically, fits sections to page budgets using a 6-stageMinimumInvasionElasticSolver, and verifies text preservation with non-whitespaceSHA-256hashing."How do I keep formulas and merged tables intact across Word, HWP, Markdown, Excel, and HTML?"
SADT preserves nested/merged grid structures and translates equations across WordOMML, HancomHWP EQN, andLaTeXthrough a unified Equation AST compiler (./ir_schema.py).
Related MCP server: hwpx-mcp-server
2. Quickstart (Zero-Clone One-Line npx / uvx or Local Run)
Option A — Zero-Clone One-Line Run via npx or uvx (Recommended)
Run sadt-mcp directly via npm (@quanxs/sadt-mcp) or GitHub uvx with zero external pip dependencies:
# 1. Run MCP stdio server immediately via npm / npx
npx -y @quanxs/sadt-mcp
# 2. Or run directly from GitHub without cloning (uvx)
uvx --from git+https://github.com/Team-Sequence-Thaumaturge/-document-IR sadt-mcp
# 3. Or install via pip directly from GitHub
pip install git+https://github.com/Team-Sequence-Thaumaturge/-document-IR.git
sadt-mcpAdd @quanxs/sadt-mcp directly to Claude Desktop, Cursor, Windsurf, or Antigravity MCP settings (no local clone needed):
{
"mcpServers": {
"sadt-mcp": {
"command": "npx",
"args": ["-y", "@quanxs/sadt-mcp"]
}
}
}Option B — Local Clone & Development
git clone https://github.com/Team-Sequence-Thaumaturge/-document-IR.git
cd -document-IR
# Editable install or standalone execution with Python 3.10+
pip install -e .
sadt-mcp
# or: python mcp_server.pySee the interactive bilingual showcase & MCP snippet generator atQuanxs SA Labs — SADT Hub, or machine-readable agent specs in ./llms.txt and ./server.json.
3. Comparison with Common Document Tools
Feature | SADT ( |
|
|
|
Pure-Python HWP v5.0 Read & Write | Read + Write ( | Mainly Read / Extract | Not supported | Not supported |
Standalone | Supported ( | Not supported | Not supported | Not supported |
Multi-Format Coverage | 8 formats ( | HWP focus | Text / DOCX / HTML / LaTeX |
|
3-Way Equation AST Translation |
| Limited | No HWP equation support | Raw XML / manual |
Template Slot & Page-Budget Fitting | Unsupervised scanner + 6-stage solver | Not included | Not included | Not included |
Native MCP ( | Built-in ( | CLI / Python API only | CLI only | Python API only |
External Dependencies | Zero (Python 3.10+ stdlib only) | External dependencies | Haskell binary |
|
4. Architecture Overview (Zero Hardcoded Document Rules)
SADT separates content topology, specification priority resolution, equation AST compilation, numerical page-budget allocation, and format projection so no font name, paper size, section title (Q1..Q4), or page count is hardcoded in the engine:
flowchart LR
A["8-Format Input Files<br/>(.docx, .hwp, .hwpx, .md, .csv, .xlsx, .html)"] --> B["Layer 1: Unsupervised Heading Spectrum,<br/>3-Way Equation AST & Slot/Media Grid Scanner"]
U["User MCP Spec Overrides<br/>(UserSpecOverrideIR)"] --> C["Priority Spec & Numerical<br/>Page-Budget Resolver"]
B --> C
C --> D["Layer 2: 2D Grid Normalizer &<br/>6-Stage Elastic Solver (Early-Stop)"]
D --> E["Layer 3: 8-Format Projectors<br/>(.hwp, .hwpx, .docx, .md, .csv, .xlsx, .html, .pdf)"]
E --> F["Consistency & Layout Verifier<br/>(Non-Whitespace SHA-256 + 3-Tier PDF Check)"]4.1. 3-Tier Specification Priority Resolution
Runtime formatting, font families, font sizes, margins, and paper sizes are resolved using the priority rule in ./ir_schema.py:
$$\text{EffectiveSpec} = \text{Priority 1 }(\text{UserSpecOverrideIR}) \succ \text{Priority 2 }(\text{TargetDocumentSpecIR}) \succ \text{Priority 3 }(\text{SourceDocumentSpecIR})$$
Priority 1 —
UserSpecOverrideIR: Explicit user or agent constraints passed through MCP calls (body/table font families and point sizes, line spacing min/max percentages, page dimensions and margins in millimeters, total page limit, per-section page budgets, outer table policy, and attachment captions).Priority 2 —
TargetDocumentSpecIR(./codec_hwp_v5.py): Dynamically extracted from the target HWP template binary streams (DocInfofont/char/para recordsTag 19,Tag 21,Tag 25andSection0..SectionNpage definitionsTag 73, cover/preamble blocks,NxMcontainer tablesSLOT 01..M, and alternating2R x Cmedia gridsMEDIA 01..P).Priority 3 —
SourceDocumentSpecIR(./codec_ooxml_owpml.py): Dynamically extracted from.docx,.hwpx, or.hwpsource documents as fallback typography when template cells contain empty placeholders.
4.2. Unsupervised Section & Generalized Media Grid Topology
Unsupervised Top-Level Section Detector: Estimates the statistical mode body font size $S_{\text{mode}}$ across paragraphs and identifies sections (
SEC 01..K,PREAMBLE,REFERENCES) via outline levels, multilingual structural prefixes (제1장,I.,Ⅰ.,Chapter 1,Q1.), or bold typographic size jumps ($\ge S_{\text{mode}} + 150\text{ HU}$).Universal Section Selector Matcher:
UserSpecOverrideIRaccepts generic IDs (SEC 01), slot IDs (SLOT 01), ordinal indices (1,"2"), or title substrings without any hardcoded document-specific exclusions.Generalized $2R \times C$ Media Grid Scanner: Detects even-row grid tables ($R \ge 1, 1 \le C \le 4$) where image rows ($H_{2r} \ge 3000\text{ HU}$) alternate with compact caption rows ($H_{2r} \ge 2 \cdot H_{2r+1}$), registering
MEDIA 01..P(SlotSpecIR).
4.3. Elastic Layout & Multi-Format Codecs
6-Stage
MinimumInvasionElasticSolver(./elastic_solver.py): Adjusts section content smoothly across progressive stages (Stage 1 empty spacer cleanup $\to$ Stage 2 line-spacing interpolation $\to$ Stage 3 standalone subheading inline lead-in $\to$ Stage 4 shortest table cell paragraph pair merge $\to$ Stage 5 shortest body continuation merge $\to$ Stage 6 optional-0.5ptfont scaling) and stops immediately once the resolved page budget is met.Standalone OWPML (
.hwpx) Package Synthesis & Lifting: Generates compliant.hwpxarchives (mimetype,META-INF/container,Contents/content,Contents/header,Contents/section0) with injected<hp:pic>/Contents/BinData/media even without a base.hwpxfile, and lifts existing.hwpxfiles back intoSectionIR.3-Way Equation AST Compiler: Parses and compiles mathematical expressions across Word
OMML(<m:oMath>), HancomHWP EQN(Tag 105in.hwpand<hp:equation>in.hwpx), andLaTeX($...$/$$...$$in Markdown and<math data-latex="...">in HTML).Bidirectional
.xlsx&.html+ Pure-Python.pdf: Supports shared strings,<mergeCells>,rowspan/colspan, base64 media, and built-in multi-page PDF 1.4 rendering with Type0/CIDFontType2 UTF-16BE (<FEFF...>) CJK strings paired with 3-tier PDF inspection (Tier 1 MS Word COM $\to$ Tier 2 LibreOffice $\to$ Tier 3 Built-in PDF 1.4).
4.4. Defensive Security & State Isolation Checks ([SEC-01] ~ [SEC-06])
[SEC-01]Rejects XMLDOCTYPEandENTITYdeclarations (XXE defense) and enforces a64 MBXML input ceiling.[SEC-02]Blocks ZIP traversal (../, drive prefixes), limits archive entries (4,096) and decompressed sizes (64 MB/entry,256 MBtotal), and uses bounded streamingzlibdecompression in.hwpstreams (64 MBceiling).[SEC-03]Checks MS-CFB headers, caps directory entries (8,192) and stream reads (128 MB), and tracks visited sectors acrossDIFAT,FAT, andMiniFATchains (CFBArchive) to exit cyclic structures safely.[SEC-04]Validates local paths against null bytes and Windows reserved device filenames.[SEC-05]Strips illegal XML 1.0 control characters and prefixes leading spreadsheet formula symbols (=,+,-,@) with an apostrophe to mitigate DDE injection.[SEC-06]Deep-copiesSectionIR.blocksbefore solving so repeated runs on the same job remain repeatable, bounded by a64-job LRU cache (TdirBetaMcpServer).
5. Repository Structure
Module Path | Description |
PEP 621 zero-dependency packaging metadata ( | |
Official MCP Registry manifest describing server coordinates, | |
Smithery | |
Concise AI-crawler summary for Generative Engine Optimization (GEO). | |
Detailed LLM and agent guide covering schemas, override parameters, comparisons, and scope boundaries. | |
Package exports ( | |
Canonical IR dataclasses, 3-Way Equation AST compiler, security validators ( | |
Pure-Python MS-CFB ( | |
2D table topology normalizer, numerical page-budget allocator, and 6-stage | |
HWP v5.0 binary record parser, | |
OOXML ( | |
Bidirectional Markdown, CSV/TSV, Excel ( | |
Standalone JSON-RPC 2.0 | |
14-Cohort Parametric Regression Suite ( |
6. MCP Tools & UserSpecOverrideIR Reference
The server (./mcp_server.py) communicates over JSON-RPC 2.0 (stdio) and exposes 5 tools:
# 1. Inspect source documents (.docx, .hwp, .hwpx, .md, .csv, .tsv, .xlsx, .html) & template
tdir_probe_files(source_paths: list[str], target_path: str) -> dict
# 2. Resolve specs, section-to-slot mapping, and page budgets
tdir_build_mapping_plan(
job_id: str,
user_spec_overrides: dict | None = None,
user_constraints: dict | None = None,
) -> dict
# 3. Execute conversion into ["hwp", "hwpx", "docx", "md", "csv", "xlsx", "html", "pdf"]
tdir_execute_conversion(
job_id: str,
output_prefix: str,
output_formats: list[str] | None = None,
page_body_height_hu: int | None = None,
base_hwpx_path: str | None = None,
user_spec_overrides: dict | None = None,
) -> dict
# 4. Run non-whitespace SHA-256 text consistency check and 3-tier PDF page-budget check
tdir_verify_fidelity_and_layout(job_id: str, export_pdf: bool = True) -> dict
# 5. Fine-tune an individual paragraph merge lock or table column width array
tdir_adjust_block_layout(
job_id: str,
section_uid: str,
block_index: int,
lock_unmerged: bool | None = None,
col_widths_hu: list[int] | None = None,
) -> dictExample UserSpecOverrideIR Payload
{
"body_font_family": "함초롬바탕",
"table_font_family": "함초롬돋움",
"body_font_size_pt": 11.5,
"table_font_size_pt": 9.5,
"body_line_spacing_min_pct": 122,
"body_line_spacing_max_pct": 160,
"page_width_mm": 210.0,
"page_height_mm": 297.0,
"margins_mm": {"top": 15.0, "bottom": 15.0, "left": 20.0, "right": 20.0},
"total_page_limit": 8,
"section_page_budgets": {"SEC_01": 2.0, "SEC_02": 2.0},
"preserve_outer_tables": true,
"route_media_to_attachment_slots": true,
"max_attachment_images": 3,
"allow_font_size_elastic_scaling": false,
"style_inheritance_mode": "TARGET_FIRST"
}7. 14-Cohort Regression Suite (./test_regression_suite.py)
Cohort ID | Experiment Scope | Verified Result |
| Document hierarchy & unsupervised heading spectrum ( |
|
| Numerical page-budget sweep ( |
|
| Continuous |
|
| 2D table topology collapse (stair-step |
|
| Generalized |
|
| N-to-M cross-format round-trips ( |
|
| UTF-16LE surrogate-pair |
|
| Multi-source heterogeneous merge ( |
|
| Standalone |
|
| 3-Way Equation AST compilation across |
|
| Bidirectional |
|
| Built-in multi-page PDF 1.4 rendering ( |
|
| Security checks ( |
|
| Standalone |
|
8. Frequently Asked Questions (FAQ)
Does SADT require Hancom Office or Microsoft Word to run?
No. Core conversion across.hwp,.hwpx,.docx,.xlsx,.html,.pdf,.md, and.csvruns purely with Python 3.10+ standard libraries on Windows, macOS, and Linux. External Word COM or LibreOffice is optional and used only when Tier-1 or Tier-2 PDF layout verification is desired; Tier-3 built-in PDF verification runs everywhere.Can I convert
.docxor.mdinto.hwpwithout an.hwpxbase file?
Yes. You can either project into an existing.hwpform template (SLOT 01..M) or synthesize a standalone.hwpxarchive directly with no reference.hwpxinput.How does SADT fit overflowing content into fixed-page templates?
After normalizing tables, the 6-stageMinimumInvasionElasticSolverincrementally tightens line spacing within user bounds, converts short standalone subheadings into inline lead-ins, and merges only minimal continuation blocks until the per-section page budget is met—preserving all source text characters checked viaSHA-256.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Related MCP Servers
- FlicenseAqualityDmaintenanceAn MCP server that enables LLMs to convert HWP and HWPX documents into Markdown for analysis and processing. It supports document conversion via local file paths or Base64 content across various MCP-compatible clients.2-
- AlicenseNot gradedqualityDmaintenanceAn MCP server for reading, editing, and creating Hangul Word Processor (.hwpx) files. It enables users to extract text, perform find-and-replace operations, and modify font styles through automated XML patching.35 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read, search, and modify HWPX documents directly via MCP, without requiring Hancom Word Processor. Supports pure Python, cross-platform operation.3,490 PyPI69Apache 2.0
- AlicenseAqualityDmaintenanceUnified MCP server for converting Markdown to HWPX documents or generating new HWPX files from templates while preserving formatting.7MIT