hwpx-mcp-server

[!NOTE] Tren de lanzamiento público: python-hwpx 6.2.1 → python-hwpx-automation 7.0.2 → hwpx-plugin 2.0.1 (automation 7.0.2 · plugin 2.0.1 publicados el 2026-08-16, tren de parches de reparación de guardado en Windows — reparación de guardado #98·guía de ruta de subida #75, contrato con core 34a91560759dc47a inmutable). Las coordenadas públicas solo se promocionan tras observar la verdad remota (core·automation en PyPI y plugin en GitHub Release·marketplace·instalación real en marketplace) — runbook de lanzamiento

Capa de aplicación que ofrece creación de documentos, relleno de formularios, maquetación de exámenes y flujos de trabajo de agentes seguros sobre el motor python-hwpx. La instalación básica se usa sin MCP mediante la API de Python y el CLI hwpx; el servidor del Protocolo de Contexto de Modelo (MCP) se añade cuando se necesita con el extra [mcp]. No requiere Hancom Office ni Windows, por lo que funciona incluso dentro de un chat de ChatGPT donde se ejecute Python.

Comenzar con la automatización 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 y hwpx help ejecutan el mismo CLI de tareas.

Related MCP server: hwpx-mcp-server

Comenzar con el adaptador MCP

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

Con un solo bloque en el archivo de configuración del cliente MCP se conecta el servidor hwpx — en Claude Desktop es claude_desktop_config.json, en VS Code es .vscode/mcp.json (la clave es servers en lugar de mcpServers), en Gemini CLI es ~/.gemini/settings.json, y en Cursor·Windsurf es el archivo de configuración MCP de cada editor.

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

En HWPX_AUTOMATION_WORKSPACE_ROOTS especifique las carpetas donde están los documentos (ruta absoluta o ~). En Windows se escribe como "[\"C:\\\\hwpx\"]". Si deja el valor vacío, el cliente GUI lanza el servidor desde el directorio del sistema, por lo que todas las rutas de documentos quedan bloqueadas — se recomienda especificarlo desde el principio. Para las demás opciones, consulte la tabla de variables de entorno.

Para leer documentos que no son HWPX (PDF/DOCX/XLSX/HTML/TXT) con document_to_markdown, instale también el adaptador MarkItDown con pip install "python-hwpx-automation[ingest]". Requisitos: Python >= 3.10 · python-hwpx >= 5.0.0.

Las distribuciones, importaciones, consolas y claves de configuración existentes de hwpx-mcp-server siguen funcionando durante 6.x — lista completa y reglas de mantenimiento: superficie de compatibilidad 6.x

Qué hace

En el modo básico ofrece múltiples herramientas HWPX, y en el modo avanzado (HWPX_AUTOMATION_ADVANCED=1) se añaden herramientas de inspección y verificación.

• Lectura·exploración — get_document_info, get_document_map (esquema·mapa de tablas·anclas en una sola llamada), find_text (sin guardar)

• Búsqueda·reemplazo·edición — search_and_replace, apply_document_commands (aplicación atómica de ediciones heterogéneas·dry-run·rollback·clave de idempotencia), add_tracked_edit (seguimiento de cambios)

• Tablas·relleno de formularios — transacción con preservación de bytes analyze_form_fill → apply_form_fill → verify_form_fill, table_compute (sumas·subtotales)

• Generación de documentos·documentos oficiales — create_document_from_plan declarativo, inspect_official_document_style (lint de normativa administrativa), mail_merge

• Formato·imágenes·generadores — set_paragraph_format·set_page_setup, insert_picture, tablones de fotos·placas de identificación·organigramas

• Vista previa·extracción·reparación·diagnóstico — render_preview (autoverificación HTML/PNG), hwpx_to_markdown, repair_hwpx, mcp_server_health

Más detalles: casos de uso · flujos de trabajo con prioridad de habilidades

Cómo usarlo de forma segura

No es necesario memorizar todas las herramientas desde el principio. Normalmente el flujo es así.

1. Lectura — get_document_info → get_document_outline/get_document_text → find_text, get_table_map para identificar solo las partes necesarias. (sin guardar)

2. Modificación segura — cree una copia con copy_document, aplique el cambio más pequeño (search_and_replace, set_table_cell_text, apply_document_commands), vuelva a leer para verificar y entregue la copia revisada.

La clave es copy first · smallest edit · re-read after edits. Las herramientas de modificación guardan inmediatamente al llamarse, así que el trabajo de revisión debe hacerse siempre en una copia.

El modelo envía solo la operación/plan y no edita directamente el XML crudo. La ruta de guardado normal pasa por la única puerta SavePipeline de python-hwpx, que verifica integridad·XML·OPC/ID· seguridad de apertura, y si la puerta falla no escribe nada. El handshake de capability bloquea con fail-closed el skew de versiones+hash de core/automation/plugin. Detalles de seguridad: guía de endurecimiento · identificadores de compatibilidad con nombres antiguos: superficie de compatibilidad 6.x

Contrato de ubicación — paragraph_index es el índice 0-based de los párrafos directos del cuerpo. Los párrafos dentro de tablas no se mezclan aquí; se especifican con un objeto location como {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0}, y se pueden pasar directamente los valores devueltos por get_table_map/find_text.

Variables de entorno

Las claves HWPX_MCP_* existentes con el mismo sufijo se mantienen como fallback durante 6.x; si ambas claves están presentes, HWPX_AUTOMATION_* tiene prioridad. La lista completa de claves conservadas para integración con render·workflow·oracle·plugin y las reglas de ruta de la base de datos de workflow están en superficie de compatibilidad 6.x.

Las rutas rechazan por defecto el traversal fuera del workspace y el escape de symlink, y las entradas URL solo permiten HTTPS·IP públicas. Las advertencias de concurrencia en hosts que no ofrecen rename atómico están en la guía de endurecimiento.

Contribuir

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

Agradecimientos

Funciona sobre la biblioteca principal python-hwpx y debe su existencia a los siguientes estándares y proyectos públicos.

• OWPML — Lenguaje de Marcado de Procesador de Texto Abierto (KS X 6101) — el estándar industrial coreano en el que se basa HWPX

• hancom-io/hwpx-owpml-model — modelo de referencia de la estructura de elementos OWPML · neolord0/hwpxlib — corpus de muestra de oracle

• edwardkim/rhwp — inspiración para el diseño de la puerta de idempotencia y verificación

Licencia · Mantenedor

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