HWP-MCP (한글 Model Context Protocol)

Controle o processador de texto coreano HWP com IA para criação, edição e manipulação automatizada de documentos.

Documentação

HWP-MCP (한글 Model Context Protocol)

O HWP-MCP é um servidor Model Context Protocol (MCP) que permite que modelos de IA como o Claude controlem o processador de texto Hangul (HWP). Este projeto fornece à IA a capacidade de criar, editar e manipular documentos Hangul automaticamente.

Principais recursos

Criação e gerenciamento de documentos: criar novos documentos, abrir e salvar
Edição de texto: inserir texto, definir fontes, adicionar parágrafos
Operações com tabelas: criar tabelas, preencher dados, definir conteúdo de células
Geração de documentos prontos: criação automática de relatórios e cartas baseados em modelos
Operações em lote: recurso de lote para executar várias operações de uma só vez

Requisitos do sistema

Sistema operacional Windows
Programa Hangul (HWP) instalado
Python 3.10 ou superior (requisito do pacote mcp)
Pacotes Python obrigatórios (consulte requirements.txt)

Em macOS/Linux ou ambientes sem o Hangul instalado, o servidor também é executado; nesse caso, apenas o hwp_read_file (leitura de arquivos HWP) está disponível.

Método de instalação

Clonar o repositório:

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

Instalar as dependências:

pip install -r requirements.txt

(Opcional) Instalar o pacote MCP:

pip install "mcp<2"

Como usar

Usar com o Claude

Registre o servidor HWP-MCP no arquivo de configuração do Claude Desktop da seguinte forma:

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

Exemplos de recursos principais

Ler arquivo HWP (não requer o programa Hangul, todos os SO)

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

Criar novo documento

hwp_create()

Inserir texto

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

Criar tabela e inserir dados

# 테이블 생성
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)

Salvar documento

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

Exemplo de operação em lote

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"}}
])

Estrutura do projeto

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  # 보안 모듈

Solução de problemas

Problemas relacionados ao módulo de segurança

Por padrão, o programa Hangul exibe um aviso de segurança ao acessar arquivos externamente. Para contornar isso, usamos o módulo FilePathCheckerModuleExample.dll. Se o registro do módulo de segurança falhar, os recursos ainda funcionam, mas a caixa de diálogo de segurança pode aparecer ao abrir/salvar arquivos.

Falha na conexão com o Hangul

Se o programa Hangul não estiver em execução, a conexão pode falhar. Verifique se o programa Hangul está instalado e funcionando corretamente.

Problemas ao inserir dados em tabelas

Ao inserir dados em tabelas, a posição do cursor às vezes se comportava de forma inesperada, mas esse problema foi resolvido na versão atual. Os dados são inseridos com precisão em todas as células da tabela.

Registro de alterações

2025-03-27

Melhorias nos recursos de criação de tabelas e preenchimento de dados
- Correção do problema de tabelas aninhadas dentro de tabelas
- Separação dos recursos de criação de tabelas e preenchimento de dados
- Adição de lógica para verificar a posição atual do cursor antes de criar tabelas
- Melhoria no recurso de preencher apenas dados em tabelas existentes
Melhorias no gerenciamento do projeto
- Adição do arquivo .gitignore (exclui arquivos temporários, arquivos de cache etc.)

2025-03-25

Melhorias no recurso de inserção de dados em tabelas
- Inserção precisa de dados a partir da primeira célula
- Melhoria na lógica de seleção de células e definição da posição do cursor
- Adição do recurso de manter a posição do cursor ao inserir texto
Adição do módulo de ferramentas dedicado a tabelas (hwp_table_tools.py)
Adição da opção from_first_cell à função hwp_fill_column_numbers

Licença

Este projeto é distribuído sob a licença MIT. Para mais detalhes, consulte o arquivo LICENSE.

Como contribuir

Relatar problemas ou sugerir recursos: use as issues do GitHub.
Contribuir com código: envie um Pull Request com as alterações.

Projetos relacionados

HWP SDK: SDK oficial da Hancom
Cursor MCP
Smithery

Contato

Para dúvidas sobre o projeto, use as issues do GitHub ou entre em contato pelo 코난쌤.