python-hwpx-automation MCP
MCP-сервер и CLI для корейских документов HWPX: правка текста и таблиц, заполнение форм, создание документа по плану.
- 69 ★ репозитория
- Последний коммит
Расширенный доступ
Почему такой уровень
- Инструменты правки сохраняют изменения в документы сразу, работа ограничена каталогами из `HWPX_AUTOMATION_WORKSPACE_ROOTS`.
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add mcp/python-hwpx-automationОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Инструменты правки сохраняют изменения в документы сразу, работа ограничена каталогами из `HWPX_AUTOMATION_WORKSPACE_ROOTS`.
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
python-hwpx-automation — прикладной слой над движком `python-hwpx` для документов HWPX, формата корейского офисного пакета Hancom. Пакет дает Python API, команду `hwpx` и необязательный MCP-сервер `hwpx-automation-mcp`. Агент читает структуру документа, ищет и заменяет текст, правит таблицы, заполняет бланки по схеме «анализ, заполнение, проверка», делает рассылку по шаблону, создает документ из декларативного плана, строит предпросмотр и чинит поврежденные файлы. Hancom Office и Windows не нужны. Модель присылает операции, сырой XML она не правит. Сохранение идет через единый контроль целостности: если проверка не проходит, файл не записывается. Для небольших локальных моделей есть профиль `minimal` с шестью инструментами. Рекомендуемый порядок работы: сначала копия документа, потом минимальная правка, потом повторное чтение результата.
Для кого. Тем, кто готовит корейские официальные документы и бланки в HWPX и поручает агенту заполнение и правки.
Подходит, если
- Бланк HWPX надо заполнить по данным и проверить результат перед отправкой.
- Нужна рассылка документов по шаблону с подстановкой полей.
- Агент заменяет текст в HWPX, а оформление документа должно сохраниться.
- Новый документ собирают из JSON-плана с заголовками, абзацами и таблицами.
Не подходит, если
- Основная задача связана с DOCX или PDF: сервер рассчитан на HWPX, остальные форматы только читаются через дополнительный пакет.
- Нужен PDF с точной версткой Hancom: рендер требует установленного на компьютере Hancom Office.
- Файлы лежат вне разрешенных каталогов: пути за пределами `HWPX_AUTOMATION_WORKSPACE_ROOTS` сервер блокирует.
Пример запроса к агенту
Скопируй `report.hwpx`, подставь в таблицу значения из `data.csv`, перечитай результат и покажи расхождения.MCP
- Транспорт
- stdio
- Авторизация
- не нужна
Переменные окружения
HWPX_AUTOMATION_WORKSPACE_ROOTSобязательная- JSON-массив каталогов, в которых разрешена работа с документами.
HWPX_AUTOMATION_PROFILE- Значение `minimal` оставляет шесть инструментов для небольших моделей.
HWPX_AUTOMATION_ADVANCED- Значение `1` включает инструменты проверки и диагностики.
Ограничения
Нужны Python 3.10 или новее и `python-hwpx` не ниже 6.5.0. Инструменты правки сохраняют файл сразу, поэтому работайте с копией документа: по умолчанию перед записью создается резервная копия `.bak`. Клиенты с графическим интерфейсом запускают сервер из системного каталога, поэтому каталоги с документами задают в `HWPX_AUTOMATION_WORKSPACE_ROOTS` сразу. Чтение PDF, DOCX и XLSX требует дополнительного пакета `[ingest]`. README и большая часть документации написаны по-корейски.
Как отключить. Удалите блок `hwpx` из настроек MCP-клиента и при необходимости выполните `pip uninstall python-hwpx-automation`. Резервные копии `.bak` рядом с документами удаляются вручную.
Частые вопросы
Как подключить MCP-сервер?
Установите пакет с extra `[mcp]` и добавьте в конфигурацию клиента сервер `hwpx` с командой `uvx` и аргументами `--from`, `python-hwpx-automation[mcp]==7.3.1`, `hwpx-automation-mcp`. Конфигурацию дают для Claude Desktop, VS Code, Gemini CLI, Cursor и Windsurf.
Нужен ли Hancom Office?
Нет. Правка, заполнение форм и создание документов работают без Hancom Office и без Windows. Он нужен только для рендера PDF командой `hwpx render-pdf`.
Что делать с моделью, которая путается в инструментах?
Запустите сервер с профилем `minimal`: `hwpx-automation-mcp --profile minimal`. Остаются шесть инструментов, например `read_outline`, `apply_text_changes` и `validate_document`.
Как защитить исходный документ?
Сначала вызовите `copy_document`, правьте копию и перечитайте результат. Перед записью по умолчанию создается `.bak` (`HWPX_AUTOMATION_AUTOBACKUP=1`).
Можно ли пользоваться без MCP?
Да. Базовая установка дает Python API и команду `hwpx`, а MCP-сервер добавляется extra `[mcp]`.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыMCP-сервер читает, правит и создает корейские документы HWP и HWPX без Hancom Office на macOS, Windows и Linux.
Скилл создает и правит документы HWPX, конвертирует HWP, собирает официальные письма и отчеты по JSON-спецификации
Скилл читает, создает и правит корейские документы hwp и hwpx прямо из агента, без Hancom Office и без конвертации
CLI и MCP-сервер переводят корейские HWP и HWPX, PDF и Office-файлы в Markdown и заполняют формы по шаблонам
Adeu: MCP, навык и CLI для правки .docx через агента с настоящими Track Changes, комментариями и сравнением версий.
MCP Word для правки документов docx с рецензированием: вставки и удаления видны в Word, комментарии, сноски, сравнение версий и журнал изменений
Сравнение с похожими
Карточки с тем же главным запросом: чем они отличаются.
| Инструмент | Официальный | Авторизация | Звезды репозитория | Главное отличие |
|---|---|---|---|---|
| python-hwpx-automation (эта карточка) | нет | не нужна | 69 | |
| hwp-mcp | нет | не нужна | 107 | читает, правит и создает HWP и HWPX; здесь упор на заполнение форм, откат правок, рассылку и профиль для малых моделей |
| hwpx-skill | нет | 308 | скилл с конвертацией HWP и сборкой писем; здесь сервер с MCP-инструментами и CLI |
Коротко о README
Пакет входит в связку из трех проектов: движок `python-hwpx`, этот прикладной слой и набор плагинов `hwpx-plugins`, который помогает агенту выбирать инструменты. В репозитории лежат примеры скиллов для заполнения форм, правки с сохранением ссылок и генерации по шаблону.