hwp-mcp

Сервер, позволяющий читать, редактировать и создавать документы Hangul (.hwp / .hwpx) в ИИ, совместимых с MCP, таких как Claude, Cursor, ChatGPT и другие.

hwp-mcp — это сервер Model Context Protocol (MCP), который позволяет ИИ-агентам напрямую работать с документами Hancom Office. Возможно не только чтение, но и редактирование текста, заполнение шаблонов и создание новых документов.

Что это за проект?

Этот проект состоит из двух частей:

• 🔧 Что сделал rhwp (основной движок) — rhwp от Edward Kim — это open-source движок, реализованный на Rust + WebAssembly, который с помощью обратной разработки полностью раскрыл закрытые форматы Hangul (HWP 5.0 binary, HWPX/OWPML). Парсинг, извлечение таблиц, изображений, формул, колонтитулов, рендеринг SVG, API полей Hancom — все эти ключевые возможности предоставляет rhwp. Без rhwp этого проекта бы не существовало.

• 🤝 Что сделал hwp-mcp (адаптер для агентов) — тонкий слой MCP-сервера поверх @rhwp/core. Мы добавили:

  • Инструменты, понятные агентам, такие как read_hwp, fill_hwp_template, replace_hwp_text, чтобы LLM (например, Claude/Cursor) могли вызывать их на естественном языке.

  • Сценарный обходчик (traversal walker), который разом выгружает основной текст, таблицы, изображения, колонтитулы, сноски и формулы.

  • Слой удобства использования, такой как автоматическая обработка объединения ячеек таблиц, автоматическое объединение сносок/формул.

  • Слой мутации на уровне ZIP-архива .hwpx для обхода ограничений exportHwpx в rhwp 0.7.7 (ключевой элемент, делающий запись возможной).

  • Пакет npm hwp-mcp (установка одной командой) + загрузчик Node.js WASM.

Итог: Адаптер, который позволяет ИИ по-настоящему читать и писать документы Hangul. Пожалуйста, выражайте благодарность за все возможности работы с Hangul проекту rhwp 🙏

Related MCP server: HWP-MCP

Установка

Claude Code

claude mcp add hwp-mcp -- npx -y hwp-mcp

Claude Desktop / Cursor / VS Code (settings JSON)

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

Требуется Node.js 20 или выше.

Список инструментов

Это 34 MCP-инструмента, предоставляемых hwp-mcp v0.2. Чтение/рендеринг поддерживаются для обоих форматов (.hwp/.hwpx), запись — только для .hwpx.

Чтение (5)

Мета / Запросы (5)

Визуальный рендеринг (4)

Запись — Текст (5)

Запись — Структура (9)

Запись — Форматирование (2)

Запись — Изображения / Таблицы / Новое (4)

Матрица извлечения контента

Матрица записи

Запись бинарных файлов .hwp не поддерживается в v0.2 из-за ограничений exportHwp в rhwp 0.7.7. Пожалуйста, сохраните файл как .hwpx в Hancom Office перед использованием инструментов записи или дождитесь релиза v0.3.

Примеры использования

Чтение правительственного документа Hangul

나: /Users/me/2026년_시행계획.hwpx 읽어줘

AI: # 2026년_시행계획.hwpx
    형식: .HWPX | 문단: 153개 | 표: 15개 | 이미지: 2개

    Ⅰ. 추진 배경
    □ (글로벌 현황) 전세계 AI 솔루션 시장 규모는 ...

    ### 표 9 (7행 x 4열)
    | 도메인 | 입력 데이터 | 학습 내용 | 산업AI 솔루션 적용 기능 예시 |
    | --- | --- | --- | --- |
    | 기계 | · 센서 데이터 로그 ... | ... | ... |

Заполнение шаблона

나: /path/to/form.hwpx 에서 {{이름}}=남대현, {{회사}}=포텐랩 으로 채워줘

AI: 저장 완료 (saved): form_filled.hwpx
    총 2건 치환 (2 replacements)
      '{{이름}}' → 1건
      '{{회사}}' → 1건

Замена текста

나: /path/to/doc.hwpx 의 "산업AI" 를 "산업-AI" 로 바꿔줘

AI: '산업AI' → '산업-AI': 18건 교체 (replaced 18)
    저장 (saved): doc_modified.hwpx

Создание нового .hwpx

나: employees.hwpx 에 "사원 명부" 와 "두 번째 줄" 두 줄을 가진 문서 만들어줘

AI: HWPX 문서 생성 완료 (created): employees.hwpx

Извлечение изображений

나: /path/to/document.hwpx 에서 이미지 빼줘

AI: 이미지 2개를 추출했습니다 (extracted 2 images):
    저장 위치: /path/to/document_images
      - image_001.bmp
      - image_002.bmp

Рендеринг страницы в SVG (для визуального анализа)

나: /path/to/document.hwpx 의 첫 페이지를 SVG로 보여줘

AI: <svg xmlns="..." width="793" height="1122" viewBox="...">
    <defs>...</defs>
    ...
    </svg>

Или сохранение на диск:

나: /path/to/document.hwpx 모든 페이지 SVG로 저장해줘

AI: 9/9 페이지 SVG 저장 (rendered 9/9 pages):
    저장 위치: /path/to/document_pages
      - page_001.svg
      - page_002.svg ...

Ограничения

Известные ограничения hwp-mcp v0.2:

• Запись .hwp не поддерживается — чтение работает для обоих форматов. Запись — только для .hwpx. При вызове инструментов записи для .hwp будет возвращено понятное сообщение об ошибке. Пожалуйста, сохраните файл как .hwpx в Hancom Office или дождитесь релиза v0.3.

• Отказ от кросс-форматного сохранения — ввод .hwpx сохраняется только как .hwpx.

• Колонтитулы/сноски извлекаются, текстовые поля/концевые сноски/формулы — в v0.3 — в результате read_hwp_text колонтитулы отображаются как блоки --- headers ---, --- footers ---, сноски — как --- footnotes ---. Извлечение текста из текстовых полей, концевых сносок и формул запланировано на v0.3.

• Поиск не работает, если поисковый запрос разбит между двумя текстовыми узлами — например, если один <hp:t> заканчивается на "пром", а следующий начинается с "ышленность", то "промышленность" не будет найдено. Это ограничение такое же, как в hwpctl от Hancom.

• Таблицы в create_hwpx_document в v0.2 выравниваются в текстовые строки — настоящие таблицы OWPML будут в v0.3.

Как это работает?

• Чтение: @rhwp/core (Rust+WASM парсер rhwp) обходит разделы, абзацы, таблицы (включая объединенные ячейки) и изображения.

• Запись (.hwpx): Парсит Contents/section*.xml внутри ZIP-архива напрямую, выполняет поиск/замену текстовых узлов <hp:t> и перепаковывает (mimetype остается согласно спецификации). Это слой для обхода проблем с round-trip exportHwpx() в rhwp.

• Новый документ: Создается с помощью createBlankDocument + insertText в rhwp, затем сохраняется через exportHwpx (текстовый round-trip стабилен).

Кредиты

rhwp (@edwardkim) — основной парсер, рендерер, Field API. Вся работа по открытию закрытого формата Hangul является фундаментом этого проекта. Если есть возможность, поддержите и этот проект: https://github.com/edwardkim/rhwp

hwp-mcp — тонкий MCP-адаптер поверх rhwp, позволяющий ИИ-агентам вызывать функции на естественном языке. Все ключевые возможности принадлежат rhwp, мы лишь обеспечили связь с LLM.

Покрытие

Оставшиеся крупные пункты для v0.3: запись бинарных .hwp, диаграммы, определение·применение стилей, извлечение текста из текстовых полей, 30 действий hwpctl (исключены намеренно).

English

hwp-mcp is an MCP server for reading and writing Korean Hangul (.hwp / .hwpx) documents from Claude / Cursor / ChatGPT and any MCP-compatible client. Read works for both formats; write currently supports .hwpx (find/replace, template fill, create new doc) — .hwp write is planned for v0.3. Built on top of rhwp (Rust + WebAssembly HWP engine by Edward Kim, MIT). Install: claude mcp add hwp-mcp -- npx -y hwp-mcp.

License

MIT.