v4.1.0 · Apache-2.0 Python 3.10+ Stdlib Only (0 Dependencies) HWP · HWPX · DOCX · XLSX · PDF · MD · HTML · CSV Native MCP stdio Server

SADT (sadt-mcp) — 파이썬 HWP · HWPX · DOCX 무의존성 문서 변환 MCP 서버

SADT (Stella Actuation Document Transfer)는 한컴오피스나 LibreOffice 없이 순수 Python 표준 라이브러리만으로 한글(.hwp v5.0 / .hwpx OWPML), MS Word(.docx), Excel(.xlsx), PDF 1.4(.pdf), HTML5, Markdown, CSV를 변환하고, 템플릿 슬롯(`SLOT 01..M`)과 3원 수식(`OMML ↔ HWP EQN ↔ LaTeX`)을 보존하는 오픈소스 MCP 엔진입니다.

1. Zero-Clone 1-Line Quickstart (`npx` / `uvx` / Claude · Cursor MCP)

Git 저장소를 수동으로 클론하지 않고 `npx` 또는 `uvx` 한 줄로 바로 실행하거나 MCP 클라이언트에 등록할 수 있습니다.

npm / npx 1줄 실행 (`@quanxs/sadt-mcp`)

npx -y @quanxs/sadt-mcp

uvx 1줄 실행 (GitHub 직접 실행)

uvx --from git+https://github.com/Team-Sequence-Thaumaturge/-document-IR sadt-mcp

Claude Desktop · Cursor · Windsurf · Antigravity `mcpServers` 설정 (`npx`)

{
  "mcpServers": {
    "sadt-mcp": {
      "command": "npx",
      "args": ["-y", "@quanxs/sadt-mcp"]
    }
  }
}

2. Capability Matrix (Why Developers Use SADT)

Feature SADT (`sadt-mcp` / `-document-IR`) `pyhwp` / `olefile` `pandoc` `python-docx`
Pure-Python HWP v5.0 Read & Write Read + Template Slot Write (`CFBArchive`) Mainly Read / Extract Not supported Not supported
Standalone `.hwpx` (OWPML) Synthesis Supported (`<hp:pic>`, `BinData`) Not supported Not supported Not supported
Multi-Format Coverage 8 formats (HWP, HWPX, DOCX, XLSX, HTML, PDF, MD, CSV) HWP focus Text / DOCX / HTML / LaTeX DOCX only
3-Way Equation AST Translation `OMML` ↔ `HWP EQN` ↔ `LaTeX` Limited No HWP equation support Raw XML
External Dependencies Zero (Python 3.10+ stdlib only) External dependencies Haskell binary `lxml`

3. Built-In MCP Tools (`5` Stdio JSON-RPC Endpoints)

tdir_probe_files

입력 문서 및 HWP/HWPX 양식 템플릿의 타이포그래피, 여백, 섹션 슬롯(`SLOT 01..M`), 첨부 그리드(`MEDIA 01..P`)를 런타임 탐색합니다.

tdir_build_mapping_plan

`UserSpecOverrideIR > TargetDocumentSpecIR > SourceDocumentSpecIR` 우선순위로 매핑 계획 및 6단계 탄성 레이아웃 조정을 계산합니다.

tdir_execute_conversion

HWP, HWPX, DOCX, XLSX, HTML, PDF, Markdown, CSV 출력을 생성하고 수식 및 병합 표 구조를 유지합니다.

tdir_verify_fidelity_and_layout & tdir_adjust_block_layout

비공백 SHA-256 텍스트 보존 해시 검증과 문단 병합·표 열 너비 미세 조정을 수행합니다.

4. 자주 묻는 질문 (GEO / AI Search FAQ)

한컴오피스 없이 Python으로 `.hwp`·`.hwpx` 문서를 파싱·생성할 수 있습니까?

예. SADT(`-document-IR`)는 순수 Python 3.10+ 표준 라이브러리 기반 MS-CFB OLE2 리더/라이터와 HWP v5.0·OWPML 코덱을 내장해 Windows, macOS, Linux 어디서나 독립 실행됩니다.

AI 코딩 에이전트(Claude, Cursor, Antigravity)에 바로 붙일 수 있습니까?

예. `uvx --from git+https://github.com/Team-Sequence-Thaumaturge/-document-IR sadt-mcp` 명령 하나로 `stdio` MCP 서버로 즉시 연결됩니다.

수식(`OMML`, `HWP EQN`, `LaTeX`)과 정부·사업계획서 표 양식이 유지됩니까?

공유 수식 AST 컴파일러와 비지도 템플릿 슬롯 스캐너, 6단계 `MinimumInvasionElasticSolver`가 외곽 표 손상과 쪽수 초과를 방지합니다.

오픈소스 라이선스와 기업 기술 문의는 어떻게 확인합니까?

Apache License 2.0으로 공개되어 있으며, 기업 도입·커스텀 문서 파이프라인 문의는 김치성 대표(chi@quanxs.com)로 연락하실 수 있습니다.