python-hwpx-automation：AI agent に HWPX 文書を安全に扱わせる
多くの agent tool は code の編集には強いが、実際の office document format を扱うと急に弱くなる。特に HWPX のように、韓国の office workflow では現実に使われる一方、一般的な developer toolchain ではかなり niche な format ではそうだ。Agent に form を埋めさせたい、公文書を検査させたい、内容を Markdown に抽出したいと思っても、model が text を読めることと、構造の壊れていない HWPX package を安全に書き戻せることは別問題である。
今日見るのは airmang/python-hwpx-automation。これは汎用の「document chatbot」ではない。python-hwpx engine の上にある Python automation layer で、Python API、hwpx CLI、optional MCP adapter を提供し、agent が local workspace 内の HWPX document を read、edit、generate、form-fill、validate できるようにする。README は、基本利用では MCP も Hancom Office も Windows も不要だと説明している。Claude Desktop、VS Code、Gemini CLI、Cursor、Windsurf などの MCP client に接続したい場合だけ、[mcp] extra を入れる。
GitHub repository API、README、Releases、Tags、default branch commit history を 2026-08-04 時点で確認すると、airmang/python-hwpx-automation は 65 stars、23 forks。主要言語は Python、license は Apache-2.0。Repository created time は 2025-09-19 10:39:17 UTC、latest push は 2026-08-04 09:53:29 UTC。Default branch の現在の latest commit は 66ec479、commit time は 2026-08-04 09:49:01 UTC。GitHub Releases page 上の最新 release は v6.7.1、published time は 2026-08-03 10:43:30 UTC。Tags list にはすでに v7.0.1 があり、対応 commit も 66ec479 である。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | airmang/python-hwpx-automation |
| 位置づけ | HWPX document 向け Python automation layer、CLI、optional MCP server |
| Stars | 65 |
| Forks | 23 |
| 主要言語 | Python |
| ライセンス | Apache-2.0 |
| 作成日時 | 2025-09-19 10:39:17 UTC |
| Latest push | 2026-08-04 09:53:29 UTC |
| 現在の default branch commit | 66ec479、2026-08-04 09:49:01 UTC |
| 最新 GitHub Release | v6.7.1、2026-08-03 10:43:30 UTC |
| 最新 Git tag | v7.0.1 |
| キーワード | HWPX、document automation、MCP、local-first、Python、CLI、form fill |
面白いのは、境界がかなり狭いこと
MCP server や agent plugin はすでに多い。ただ、多くの project は境界が広すぎる。何でも少しずつ接続しようとして、結局どの artifact を信頼して変更できるのかが曖昧になりがちだ。python-hwpx-automation は逆で、HWPX という具体的な format に絞り、read、find、replace、table、form、document generation、preview、repair、validation を agent が呼べる tool に分解している。
README に並ぶ tool surface はかなり具体的だ。Basic read には get_document_info、get_document_map、find_text がある。Edit path には search_and_replace、apply_document_commands、add_tracked_edit がある。Form workflow は analyze_form_fill から apply_form_fill、さらに verify_form_fill へ進む。Generation side には create_document_from_plan、official document style inspection、mail merge、photo sheets、nameplates、organization chart がある。さらに render_preview、hwpx_to_markdown、repair_hwpx、health check も提供する。
この種類の project の価値は、「model が document を書けるようになった」という話ではない。LLM が直接触るには壊しやすい binary/compressed-package style の office format を、検証可能な小さな operation に変換するところにある。Agent が送るのは plan と operation であり、raw XML を直接編集するわけではない。実際の office document では、この差は大きい。必要なのは文章生成だけではなく、保存後も format、table、field、package structure が生きていることである。
MCP は入口の一つでしかない
README で興味深いのは、MCP server を optional layer として扱っている点だ。最小インストールは次の形でよい。
pip install python-hwpx-automationその後、Python から create_document_from_plan で document を作ることもできるし、python -m hwpx_automation --help や hwpx help で CLI を使うこともできる。MCP client に接続したいときだけ、次の extra を入れる。
pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcpそのため、特定の agent host だけに依存する一時的 adapter には見えない。普通の Python script や CI で document generation を先に回し、同じ capability を Claude Desktop、VS Code、Gemini CLI、Cursor、Windsurf にも出せる。Team workflow に入れるなら、「ある chat window の中でだけ使える」よりこのほうが扱いやすい。
MCP configuration には実用的な制約もある。HWPX_AUTOMATION_WORKSPACE_ROOTS で、アクセスを許す document directory を明示する必要がある。README は、空のままだと GUI client が system directory から server を起動し、document path が blocked されがちだと説明している。この default は妥当だ。Document automation tool は、最初から file system 全体を読めるべきではない。
Format conversion より安全設計が重要
Document agent の risk は code agent と少し違う。Code agent が file を壊しても、Git がある程度守ってくれる。Office document は、壊れ方が「保存はできるが開けない」「table は残っているが field がずれている」「preview と最終表示が一致しない」のようになりやすい。python-hwpx-automation の README は、copy first、smallest edit、re-read after edits を何度も強調している。Modification tool は呼び出すとすぐ保存するため、まず copy を作り、そこで最小変更を行い、再度 read して確認する流れを勧めている。
Project は save gate についても説明している。通常の save path は python-hwpx の SavePipeline を通り、integrity、XML、OPC/ID、open safety を確認する。Gate が fail した場合は何も書き込まない。Path handling では、workspace 外 traversal と symlink escape を default で拒否する。URL input は HTTPS と public IP のみを許し、private network access は明示的に有効化する必要がある。MCP scenario では capability handshake もあり、core、automation、plugin の version と hash skew を検査し、default では fail-closed になる。
こうした detail は地味だが、この手の project が本当に workflow に入るかどうかの境界でもある。「document を text にできる」tool は demo までなら十分だ。しかし「restricted workspace で小さく編集し、保存前後で検査し、fail したら書かない」tool であれば、実際の file に触る可能性が出てくる。
向いている場面
最も分かりやすいのは、韓国の business document automation だ。HWPX の meeting note、notice、公文書、test sheet、nameplate、organization chart を batch 生成したり、structured data から table field を埋めたりする。README にある form fill workflow と table_compute は、まさに「document は form のように見えるが、data は別の場所から来る」仕事に向いている。
二つ目は、HWPX を agent workflow に接続する場面だ。たとえば agent にまず get_document_map で document structure を見せ、必要な paragraph や table cell だけを編集させる。HWPX を Markdown に変換して summary させる。あるいは render_preview の後に結果を人間へ渡して確認させる。Document 全体を model に投げて「理解して」と頼むより、こちらのほうが reliable で audit しやすい。
三つ目は、non-Windows environment での HWPX handling だ。README は Hancom Office も Windows も不要で、Python が動けばよいと明記している。これは server、CI、remote agent session、ChatGPT/Codex のような execution environment では大きい。Document processing を desktop office software に縛らず、automation pipeline に置ける。
Caveat
第一の caveat は、domain がかなり強いことだ。HWPX を扱わないなら、あるいは team の document が主に DOCX、PDF、Markdown なら、この project がすぐ日常 workflow を変えることはない。価値は「全部の document tool を置き換える」ことではなく、HWPX をちゃんと扱うところにある。
第二の caveat は、release state をよく見る必要があることだ。GitHub Releases の最新は v6.7.1 だが、Tags には v7.0.1 がすでにあり、latest commit message も 7.0.1 の recovery coordinate と CI gate を説明している。つまり project は非常に active だが、version train も速い。Production script では dependency version を固定し、README の safety flow に従って copy 上で検証したほうがよい。
第三の caveat は、documentation が主に Korean であること。韓国の HWPX workflow では自然だが、中国語や日本語の team が初めて評価する場合は、少し読むコストが増える。ただし API、environment variable、command name はかなり明確なので、実装時に大量の自然言語説明へ依存する必要はない。
まとめ
airmang/python-hwpx-automation は niche だが、目的が明確な project だ。HWPX という実際の office format を、Python、CLI、MCP agent の controllable operation surface に載せている。面白いのは「また一つ MCP server が増えた」ことではなく、document editing を restricted、verifiable、re-readable な小さな step に分けていることだ。
HWPX、公文書、form、local document automation が仕事に含まれるなら、この project は tool box に入れてよい。より広い agent engineering の視点でも、よい reminder になる。Agent に file を扱わせるとき、一番重要なのは generation capability ではなく、boundary、rollback、validation である。