hwpx-mcp-server

[!NOTE] Публичный поезд: python-hwpx 6.2.1 → python-hwpx-automation 7.0.2 → hwpx-plugin 2.0.1 (automation 7.0.2 · plugin 2.0.1 выпущены 2026-08-16, поезд исправлений сохранения для Windows — исправление сохранения #98·инструкция по пути загрузки #75, контракт с core 34a91560759dc47a неизменен). Публичные координаты повышаются только после наблюдения удалённой истины (core·automation на PyPI и plugin GitHub Release·marketplace·фактическая установка из marketplace) — runbook релиза

Прикладной слой поверх движка python-hwpx, предоставляющий создание документов, заполнение форм, вёрстку экзаменационных листов и безопасные агентные рабочие процессы. Базовая установка работает через Python API и CLI hwpx без MCP, а сервер протокола контекста моделей (MCP) добавляется при необходимости через extra [mcp]. Hancom Office и Windows не требуются, поэтому всё работает даже внутри чата ChatGPT, где выполняется Python.

Начало работы с автоматизацией Python

pip install python-hwpx-automation

from hwpx_automation import create_document_from_plan

document = create_document_from_plan(
    {
        "schemaVersion": "hwpx.document_plan.v1",
        "title": "회의 결과",
        "blocks": [{"type": "paragraph", "text": "결정 사항"}],
    }
)
document.save_to_path("meeting-result.hwpx")

python -m hwpx_automation --help и hwpx help запускают один и тот же task CLI.

Related MCP server: hwpx-mcp-server

Начало работы с MCP-адаптером

pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcp

Одного блока ниже в файле конфигурации MCP-клиента достаточно, чтобы подхватить сервер hwpx — для Claude Desktop это claude_desktop_config.json, для VS Code — .vscode/mcp.json (ключ servers вместо mcpServers), для Gemini CLI — ~/.gemini/settings.json, для Cursor·Windsurf — файл конфигурации MCP соответствующего редактора.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": [
        "--from",
        "python-hwpx-automation[mcp]==7.0.2",
        "hwpx-automation-mcp"
      ],
      "env": {
        "HWPX_AUTOMATION_WORKSPACE_ROOTS": "[\"~/Documents\"]"
      }
    }
  }
}

В HWPX_AUTOMATION_WORKSPACE_ROOTS укажите папку(и) с документами (абсолютный путь или ~). На Windows пишите как "[\"C:\\\\hwpx\"]". Если оставить значение пустым, GUI-клиент запускает сервер в системном каталоге, поэтому все пути к документам будут заблокированы — рекомендуется указывать с самого начала. Остальные параметры см. в таблице переменных окружения.

Чтобы читать не-HWPX документы (PDF/DOCX/XLSX/HTML/TXT) через document_to_markdown, установите дополнительно адаптер MarkItDown: pip install "python-hwpx-automation[ingest]". Требования: Python >= 3.10 · python-hwpx >= 5.0.0.

Существующие дистрибутивы, импорты, консоль и ключи конфигурации hwpx-mcp-server продолжают работать в течение 6.x — полный список и правила поддержки: поверхность совместимости 6.x

Что умеет

В базовом режиме предоставляется множество инструментов HWPX, а в расширенном режиме (HWPX_AUTOMATION_ADVANCED=1) добавляются инструменты для проверки и валидации.

• Чтение·навигация — get_document_info, get_document_map (структура·карта таблиц·якоря одним вызовом), find_text (без сохранения)

• Поиск·замена·редактирование — search_and_replace, apply_document_commands (атомарное применение разнородных правок·dry-run·откат·идемпотентный ключ), add_tracked_edit (отслеживание изменений)

• Таблицы·заполнение форм — транзакция с сохранением байтов analyze_form_fill → apply_form_fill → verify_form_fill, table_compute (итоги·промежуточные итоги)

• Создание документов·официальные письма — декларативный create_document_from_plan, inspect_official_document_style (lint административных правил), mail_merge

• Форматирование·изображения·генераторы — set_paragraph_format·set_page_setup, insert_picture, фототаблицы·бейджи·организационные схемы

• Предпросмотр·извлечение·восстановление·диагностика — render_preview (самопроверка HTML/PNG), hwpx_to_markdown, repair_hwpx, mcp_server_health

Подробнее: примеры использования · рабочие процессы с приоритетом навыков

Как использовать безопасно

Не нужно запоминать все инструменты с самого начала. Обычно всё происходит так.

1. Чтение — get_document_info → get_document_outline/get_document_text → find_text, get_table_map, чтобы понять только нужные части. (без сохранения)

2. Безопасное изменение — создайте копию через copy_document, примените наименьшее изменение (search_and_replace, set_table_cell_text, apply_document_commands), затем перечитайте для проверки и передайте проверенную копию.

Ключевой принцип — copy first · smallest edit · re-read after edits. Инструменты редактирования сохраняют сразу при вызове, поэтому для проверочной работы обязательно используйте копию.

Модель отправляет только operation/plan и не редактирует raw XML напрямую. Обычный путь сохранения проходит через единый шлюз SavePipeline библиотеки python-hwpx, который проверяет целостность, XML, OPC/ID и безопасность открытия; если шлюз не пройден, ничего не записывается. Capability handshake блокирует расхождение версий+хешей core/automation/plugin по принципу fail-closed. Подробности безопасности: руководство по усилению · идентификаторы совместимости со старыми именами: поверхность совместимости 6.x

Контракт расположения — paragraph_index — это 0-based индекс абзаца, непосредственно входящего в тело документа. Абзацы внутри таблиц сюда не смешиваются; они задаются объектом location, например {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0}, и можно передавать значения, возвращённые get_table_map/find_text, как есть.

Переменные окружения

Существующие ключи HWPX_MCP_* с тем же суффиксом сохраняются как fallback в течение 6.x; если присутствуют оба ключа, приоритет у HWPX_AUTOMATION_*. Полный список сохранённых ключей для интеграции render·workflow·oracle·plugin и правила пути к БД workflow см. в поверхности совместимости 6.x.

По умолчанию пути отклоняют traversal за пределы workspace и symlink escape, а URL-входы допускают только HTTPS и публичные IP. Предупреждения о параллельности на хостах без атомарного rename см. в руководстве по усилению.

Участие

good first issue · вехи · Discussions · CONTRIBUTING · CHANGELOG

python -m pip install -e ".[test]"   # 테스트 의존성
python -m pytest -q                   # 전체 테스트
python scripts/run_conformance.py run \
  --tier structural --check tests/conformance/golden/structural.json

Благодарности

Работает поверх базовой библиотеки python-hwpx и опирается на следующие открытые стандарты и проекты.

• OWPML — открытый язык разметки текстовых процессоров (KS X 6101) — корейский промышленный стандарт, на котором основан HWPX

• hancom-io/hwpx-owpml-model — эталонная модель структуры элементов OWPML · neolord0/hwpxlib — образцовый корпус oracle

• edwardkim/rhwp — вдохновение для дизайна идемпотентности и шлюза валидации

License · Maintainer

Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · kokyuhyun@hotmail.com