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 released 2026-08-16, Windows 保存修復パッチトレイン — 保存修復 #98・アップロードパス案内 #75、core と契約 34a91560759dc47a 不変)。 公開座標はリモートの真実(core・automation PyPI と plugin GitHub Release・marketplace・実際の marketplace インストール)を観測した後にのみ 昇格されます — リリース runbook

python-hwpx エンジンの上で文書作成・ フォーム入力・試験問題レイアウト・安全なエージェントワークフローを提供するアプリケーションレイヤーです。 基本インストールは MCP なしで Python API と hwpx CLI で使い、 モデルコンテキストプロトコル(MCP) サーバーは必要なときに [mcp] extra で追加します。ハングルオフィスも Windows も不要なので、Python が動く ChatGPT チャット内でもそのまま動作します。

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 クライアント設定ファイルに以下のブロック 1 つで hwpx サーバーを掴みます — Claude Desktop は claude_desktop_config.json、VS Code は .vscode/mcp.json(キーが mcpServers の代わりに servers)、 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 で読むには pip install "python-hwpx-automation[ingest]" で MarkItDown adapter を一緒に インストールします。要件: Python >= 3.10 · python-hwpx >= 5.0.0。

既存の hwpx-mcp-server 配布・import・コンソール・設定キーも 6.x の間そのまま動作します — 全リストと維持ルール: 6.x 互換サーフェス

何をするか

基本モードで多数の HWPX ツールを提供し、高度モード(HWPX_AUTOMATION_ADVANCED=1)で点検・検証用ツールが追加されます。

• 読み取り・探索 — get_document_info、get_document_map(アウトライン・表マップ・アンカーを 1 回の呼び出しで)、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 を直接編集しません。通常の保存 パスは python-hwpx の単一 SavePipeline ゲートを通過して整合性・XML・OPC/ID・ 開封安全性を検査し、ゲートが失敗したら何も書き込みません。capability handshake は core/automation/plugin バージョン+ハッシュ skew を fail-closed で遮断します。 セキュリティ詳細: ハードニングガイド · 旧名との互換 識別子: 6.x 互換サーフェス

位置契約 — paragraph_index は本文直下の段落の 0-based インデックスです。表内の段落はここに混ぜず、 {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0} のような location オブジェクトで指定し、get_table_map/find_text が返した値をそのまま渡せます。

環境変数

同一 suffix の既存 HWPX_MCP_* キーは 6.x の間 fallback として維持され、両キーが 一緒にある場合は HWPX_AUTOMATION_* が優先します。render・workflow・oracle・plugin 連携用の保存キー全リストと workflow DB パスルールは 6.x 互換サーフェス にあります。

パスは基本的に workspace 外 traversal と 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 — オラクルサンプルコーパス

• edwardkim/rhwp — 冪等性・検証ゲート設計のインスピレーション

License · Maintainer

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