HWP-MCP(ハングルモデルコンテキストプロトコル)

HWP-MCPは、ClaudeなどのAIモデルがハングルワードプロセッサ（HWP）を制御できるようにするModel Context Protocol（MCP）サーバーです。このプロジェクトは、ハングル文書を自動的に作成、編集、操作する機能をAIに提供します。

主な機能

文書の作成と管理：新しい文書を作成、開く、保存する機能
テキスト編集：テキストの挿入、フォント設定、段落の追加
テーブル操作：テーブルの作成、データの入力、セルの内容の設定
完成した文書の生成：テンプレートベースのレポートと手紙の自動生成
バッチジョブ：複数のジョブを一度に実行するバッチ機能

システム要件

Windowsオペレーティングシステム
ハングル（HWP）プログラムのインストール
Python 3.7以降
必須Pythonパッケージ（requirements.txtを参照）

インストール方法

ストレージクローン：

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

依存関係のインストール：

pip install -r requirements.txt

（オプション）MCPパッケージのインストール：

pip install mcp

使用方法

Claudeで使用する

Claudeデスクトップ設定ファイルに次のようにHWP-MCPサーバーを登録します。

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

主な機能例

新しい文書の作成

hwp_create()

テキストの挿入

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

テーブルの作成とデータ入力

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

文書を保存

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

バッチジョブの例

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

プロジェクト構造

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

トラブルシューティング

セキュリティモジュールに関する問題

デフォルトでは、ハングルプログラムは外部からファイルにアクセスするとセキュリティ警告を表示します。これをバイパスするには、 FilePathCheckerModuleExample.dllモジュールを使用します。セキュリティモジュールの登録に失敗しても機能は機能しますが、ファイルを開く/保存するとセキュリティダイアログボックスが表示されることがあります。

ハングル接続失敗

ハングルプログラムが実行されていないと、接続が失敗する可能性があります。ハングルプログラムがインストールされ、正常に動作していることを確認してください。

テーブルデータ入力の問題

テーブルにデータを入力すると、カーソル位置が予想とは異なる動作をすることがありましたが、現在のバージョンではこの問題は解決されました。テーブル内のすべてのセルに正確にデータが入力されます。

変更ログ

2025-03-27

テーブルの作成とデータの埋め込み機能の改善
- テーブル内にテーブルが入れ子になる問題の解決
- 表の作成とデータの塗りつぶし機能の分離
- テーブル作成前の現在のカーソル位置チェックロジックの追加
- 既存のテーブルにデータのみを埋める機能の改善
プロジェクト管理の改善
- .gitignoreファイルの追加(一時ファイル、キャッシュファイルなどを除く)

2025-03-25

テーブルデータ入力機能の改善
- 最初のセルから正確にデータ入力可能
- セル選択とカーソル位置設定ロジックの改善
- テキスト入力時にカーソル位置保持機能を追加
テーブル専用ツールモジュール（ hwp_table_tools.py ）の追加
hwp_fill_column_numbers関数にfrom_first_cellオプションを追加

ライセンス

このプロジェクトは、MITライセンスに従って配布されます。詳細については、 LICENSEファイルを参照してください。

貢献方法

課題の提供または機能の提案：GitHub問題を使用してください。
コードの貢献：変更を含むPull Requestを送信してください。

お問い合わせ

プロジェクトに関するお問い合わせはGitHubの問題、コナンサムを介してください。

HWP MCP Server