hwpx-mcp-server

[!NOTE] Öffentlicher Zug: python-hwpx 6.2.1 → python-hwpx-automation 7.0.2 → hwpx-plugin 2.0.1 (automation 7.0.2 · plugin 2.0.1 veröffentlicht am 2026-08-16, Windows-Speicher-Reparatur-Patch-Zug — Speicher-Reparatur #98·Upload-Pfad-Hinweis #75, core und Vertrag 34a91560759dc47a unverändert). Öffentliche Koordinaten werden erst nach Beobachtung der entfernten Wahrheit (core·automation PyPI und plugin GitHub Release·marketplace·tatsächliche marketplace-Installation) hochgestuft — Release-Runbook

Eine Anwendungsschicht auf Basis der python-hwpx-Engine für Dokumenterstellung, Formularausfüllung, Prüfungsbogen-Satz und sichere Agenten-Workflows. Die Basisinstallation funktioniert ohne MCP über die Python-API und die hwpx-CLI; der Model Context Protocol (MCP)-Server wird bei Bedarf über das [mcp]-Extra hinzugefügt. Weder Hancom Office noch Windows sind erforderlich, sodass es auch direkt in einem ChatGPT-Chat mit Python funktioniert.

Erste Schritte mit der Python-Automatisierung

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 und hwpx help führen dieselbe Task-CLI aus.

Related MCP server: hwpx-mcp-server

Erste Schritte mit dem MCP-Adapter

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

Ein einziger Block in der MCP-Client-Konfigurationsdatei genügt, um den hwpx-Server zu erfassen — bei Claude Desktop ist es claude_desktop_config.json, bei VS Code .vscode/mcp.json (Schlüssel servers statt mcpServers), bei Gemini CLI ~/.gemini/settings.json, bei Cursor·Windsurf die jeweilige MCP-Konfigurationsdatei des Editors.

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

Geben Sie in HWPX_AUTOMATION_WORKSPACE_ROOTS den Ordner mit den Dokumenten an (absoluter Pfad oder ~). Unter Windows schreiben Sie es wie "[\"C:\\\\hwpx\"]". Wenn der Wert leer bleibt, startet der GUI-Client den Server im Systemverzeichnis, wodurch alle Dokumentpfade blockiert sind — es wird empfohlen, ihn von Anfang an anzugeben. Die übrigen Optionen finden Sie in der Tabelle Umgebungsvariablen.

Um Nicht-HWPX-Dokumente (PDF/DOCX/XLSX/HTML/TXT) mit document_to_markdown zu lesen, installieren Sie den MarkItDown-Adapter mit pip install "python-hwpx-automation[ingest]" mit. Anforderungen: Python >= 3.10 · python-hwpx >= 5.0.0.

Bestehende hwpx-mcp-server-Distributionen, Imports, Konsolen und Konfigurationsschlüssel funktionieren während 6.x weiterhin unverändert — vollständige Liste und Wartungsregeln: 6.x-Kompatibilitätsoberfläche

Was es tut

Im Basismodus werden zahlreiche HWPX-Werkzeuge bereitgestellt; im erweiterten Modus (HWPX_AUTOMATION_ADVANCED=1) kommen Werkzeuge für Prüfung und Validierung hinzu.

• Lesen·Navigieren — get_document_info, get_document_map (Gliederung·Tabellenkarte·Anker in einem Aufruf), find_text (speichert nicht)

• Suchen·Ersetzen·Bearbeiten — search_and_replace, apply_document_commands (atomare Anwendung heterogener Bearbeitungen·Dry-Run·Rollback·Idempotenzschlüssel), add_tracked_edit (Änderungsverfolgung)

• Tabellen·Formularausfüllen — analyze_form_fill → apply_form_fill → verify_form_fill byte-erhaltende Transaktion, table_compute (Summen·Zwischensummen)

• Dokumenterstellung·Amtsschreiben — deklaratives create_document_from_plan, inspect_official_document_style (Verwaltungsvorschriften-Lint), mail_merge

• Formatierung·Bilder·Generatoren — set_paragraph_format·set_page_setup, insert_picture, Fototafel·Namensschild·Organigramm

• Vorschau·Extraktion·Reparatur·Diagnose — render_preview (HTML/PNG-Selbstvalidierung), hwpx_to_markdown, repair_hwpx, mcp_server_health

Weitere Details: Anwendungsfälle · Skill-first-Workflows

Sichere Verwendung

Sie müssen nicht von Anfang an alle Werkzeuge auswendig lernen. Normalerweise läuft es so ab:

1. Lesen — get_document_info → get_document_outline/get_document_text → find_text, get_table_map, um nur die benötigten Teile zu erfassen. (Speichert nicht)

2. Sichere Bearbeitung — Mit copy_document eine Kopie erstellen, die kleinste Änderung (search_and_replace, set_table_cell_text, apply_document_commands) anwenden, danach erneut lesen und prüfen, dann die geprüfte Kopie übergeben.

Der Kern ist copy first · smallest edit · re-read after edits. Bearbeitungswerkzeuge speichern sofort beim Aufruf, daher müssen Überprüfungsarbeiten unbedingt an einer Kopie durchgeführt werden.

Das Modell sendet nur Operationen/Pläne und bearbeitet das rohe XML nicht direkt. Der normale Speicherpfad durchläuft das einzelne SavePipeline-Gate von python-hwpx, das Integrität·XML·OPC/ID· Öffnungssicherheit prüft; schlägt das Gate fehl, wird nichts geschrieben. Der Capability-Handshake blockiert core/automation/plugin-Versions- und Hash-Skews fail-closed. Sicherheitsdetails: Härtungsleitfaden · Kompatibilitätskennungen mit alten Namen: 6.x-Kompatibilitätsoberfläche

Positionsvertrag — paragraph_index ist der 0-basierte Index eines Absatzes direkt im Haupttext. Absätze in Tabellen werden hier nicht gemischt, sondern über ein location-Objekt wie {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0} angegeben; die von get_table_map/find_text zurückgegebenen Werte können direkt übergeben werden.

Umgebungsvariablen

Bestehende HWPX_MCP_*-Schlüssel mit gleichem Suffix bleiben während 6.x als Fallback erhalten; wenn beide Schlüssel vorhanden sind, haben HWPX_AUTOMATION_* Vorrang. Die vollständige Liste der erhaltenen Schlüssel für Render·Workflow·Oracle·Plugin- Integration und die Regeln für den Workflow-DB-Pfad finden Sie in der 6.x-Kompatibilitätsoberfläche.

Pfade lehnen standardmäßig Traversal außerhalb des Workspace und Symlink-Escapes ab; URL-Eingaben erlauben nur HTTPS·öffentliche IPs. Hinweise zur Nebenläufigkeit auf Hosts ohne atomares Rename finden Sie im Härtungsleitfaden.

Mitwirken

good first issue · Meilensteine · 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

Danksagungen

Funktioniert auf der Kernbibliothek python-hwpx und verdankt den folgenden öffentlichen Standards und Projekten viel.

• OWPML — Open Word Processor Markup Language (KS X 6101) — der koreanische Industriestandard, auf dem HWPX basiert

• hancom-io/hwpx-owpml-model — Referenzmodell der OWPML-Elementstruktur · neolord0/hwpxlib — Oracle-Beispielkorpus

• edwardkim/rhwp — Inspiration für das Idempotenz- und Validierungs-Gate-Design

License · Maintainer

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