HWP-MCP (한글 Model Context Protocol)

HWP-MCP (한글 Model Context Protocol)

HWP-MCP es un servidor de Model Context Protocol (MCP) que permite a modelos de IA como Claude controlar el procesador de textos Hangul (HWP). Este proyecto proporciona a la IA la capacidad de crear, editar y manipular documentos Hangul automáticamente.

Funciones principales

• Creación y gestión de documentos: funciones para crear, abrir y guardar documentos nuevos
• Edición de texto: inserción de texto, configuración de fuentes, adición de párrafos
• Trabajo con tablas: creación de tablas, llenado de datos, configuración del contenido de celdas
• Generación de documentos completos: creación automática de informes y cartas basados en plantillas
• Procesamiento por lotes: función de lote que ejecuta múltiples operaciones a la vez

Requisitos del sistema

• Sistema operativo Windows
• Programa Hangul (HWP) instalado
• Python 3.10 o superior (requisito del paquete mcp)
• Paquetes de Python necesarios (consulte requirements.txt)

En macOS/Linux o en entornos sin Hangul instalado, el servidor también se ejecuta; en ese caso, solo se puede usar hwp_read_file (lectura de archivos HWP).

Método de instalación

1. Clonar el repositorio:

git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp

2. Instalar dependencias:

pip install -r requirements.txt

3. (Opcional) Instalar el paquete MCP:

pip install "mcp<2"

Cómo usar

Uso con Claude

Registre el servidor HWP-MCP en el archivo de configuración de Claude Desktop de la siguiente manera:

{
  "mcpServers": {
    "hwp": {
      "command": "python",
      "args": ["경로/hwp-mcp/hwp_mcp_stdio_server.py"]
    }
  }
}

Ejemplos de funciones principales

Leer archivo HWP (no requiere el programa Hangul, todos los sistemas operativos)

hwp_read_file("경로/문서.hwp")  # 본문 텍스트 반환, 표는 Markdown 표로 변환

Crear un documento nuevo

hwp_create()

Insertar texto

hwp_insert_text("원하는 텍스트를 입력하세요.")

Crear tabla e ingresar datos

# 테이블 생성
hwp_insert_table(rows=5, cols=2)

# 테이블에 데이터 채우기
hwp_fill_table_with_data([
    ["월", "판매량"], 
    ["1월", "120"], 
    ["2월", "150"], 
    ["3월", "180"], 
    ["4월", "200"]
], has_header=True)

# 표에 연속된 숫자 채우기
hwp_fill_column_numbers(start=1, end=10, column=1, from_first_cell=True)

Guardar documento

hwp_save("경로/문서명.hwp")

Ejemplo de procesamiento por lotes

hwp_batch_operations([
    {"operation": "hwp_create"},
    {"operation": "hwp_insert_text", "params": {"text": "제목"}},
    {"operation": "hwp_set_font", "params": {"size": 20, "bold": True}},
    {"operation": "hwp_save", "params": {"path": "경로/문서명.hwp"}}
])

Estructura del proyecto

hwp-mcp/
├── hwp_mcp_stdio_server.py  # 메인 서버 스크립트
├── requirements.txt         # 의존성 패키지 목록
├── hwp-mcp-구조설명.md       # 프로젝트 구조 설명 문서
├── src/
│   ├── tools/
│   │   ├── hwp_controller.py  # 한글 제어 핵심 컨트롤러
│   │   └── hwp_table_tools.py # 테이블 관련 기능 전문 모듈
│   ├── utils/                 # 유틸리티 함수
│   └── __tests__/             # 테스트 모듈
└── security_module/
    └── FilePathCheckerModuleExample.dll  # 보안 모듈

Solución de problemas

Problemas relacionados con el módulo de seguridad

De forma predeterminada, el programa Hangul muestra una advertencia de seguridad cuando se accede a archivos desde el exterior. Para evitar esto, se utiliza el módulo FilePathCheckerModuleExample.dll. Si el registro del módulo de seguridad falla, las funciones siguen funcionando, pero puede aparecer un cuadro de diálogo de seguridad al abrir/guardar archivos.

Error de conexión con Hangul

Si el programa Hangul no está en ejecución, la conexión puede fallar. Verifique que el programa Hangul esté instalado y funcionando correctamente.

Problemas al ingresar datos en tablas

Al ingresar datos en tablas, la posición del cursor a veces se comportaba de manera inesperada, pero este problema se ha resuelto en la versión actual. Los datos se ingresan con precisión en todas las celdas de la tabla.

Registro de cambios

2025-03-27

• Mejora de las funciones de creación de tablas y llenado de datos
  • Se resolvió el problema de tablas anidadas dentro de tablas
  • Se separaron las funciones de creación de tablas y llenado de datos
  • Se agregó lógica para verificar la posición actual del cursor antes de crear una tabla
  • Se mejoró la función de llenar solo datos en tablas existentes
• Mejora de la gestión del proyecto
  • Se agregó el archivo .gitignore (excluye archivos temporales, archivos de caché, etc.)

2025-03-25

• Mejora de la función de ingreso de datos en tablas
  • Posibilidad de ingresar datos con precisión desde la primera celda
  • Mejora de la lógica de selección de celdas y configuración de la posición del cursor
  • Se agregó la función de mantener la posición del cursor al ingresar texto
• Se agregó el módulo de herramientas dedicado a tablas (hwp_table_tools.py)
• Se agregó la opción from_first_cell a la función hwp_fill_column_numbers

Licencia

Este proyecto se distribuye bajo la licencia MIT. Para más detalles, consulte el archivo LICENSE.

Cómo contribuir

1. Reporte de problemas o sugerencias de funciones: use los issues de GitHub.
2. Contribución de código: envíe un Pull Request con los cambios.

Proyectos relacionados

• HWP SDK: SDK oficial de Hancom
• Cursor MCP
• Smithery

Contacto

Para consultas relacionadas con el proyecto, use los issues de GitHub o contacte a 코난쌤.