Hwp MCP

🚀 HWP MCP サーバー

MCP（Model Context Protocol）サーバーで、LLMがHWP COM APIを介してバイナリHWP（한글）ドキュメントを読み書きできるようにします。

🚀 クイックスタート

LLMはMCPサーバーを通じて、PowerShellブリッジを経由してHWP COM APIにアクセスし、한글ドキュメントを操作することができます。以下に、サーバーの起動方法や設定例を示します。

✨ 主な機能

• LLMとHWPドキュメントの連携を可能にする。
• 140種類以上のMCPツールを提供し、ドキュメントの管理、読み取り、書き込み、書式設定など様々な操作ができる。

📦 インストール

uv pip install -e .

💻 使用例

基本的な使用法

MCPサーバーの起動

python -m hwp_mcp.server

Claude Desktopの設定

{
  "mcpServers": {
    "hwp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hwp-mcp", "hwp-mcp"]
    }
  }
}

📚 ドキュメント

MCPツール (140)

HWP COM API 199 HParameterSet 100%カバー

ドキュメント管理 (5)

読み取り (5)

書き込み (5)

書式設定 (3)

テーブル (3)

高度な機能 (5)

カーソルとナビゲーション (11)

フィールド (12)

高度なテーブル (11)

拡張書式設定 (5)

ページとセクション (10)

画像と数式 (3)

フォームコントロール (3)

ドキュメント情報 (5)

印刷とエクスポート (3)

ユーティリティ (4)

ブックマークとハイパーリンク (6)

ヘッダー/フッターとキャプション (2)

ドキュメント操作 (8)

互換性と設定 (3)

コントロールとオブジェクト (4)

スタイルとスクリプト (4)

システムとセキュリティ (11)

HParameterSetアクション (10)

プロジェクト構造

hwp-mcp/
├── src/hwp_mcp/
│   ├── __init__.py
│   ├── _core.py         # FastMCPインスタンスと共有ヘルパー
│   ├── server.py        # エントリーポイント、すべてのツールモジュールをインポート
│   ├── bridge.py        # PowerShellサブプロセスマネージャー
│   ├── commands.py      # JSONコマンドビルダー
│   └── tools/           # MCPツールの定義 (140ツール)
│       ├── cursor.py
│       ├── doc_info.py
│       ├── document.py
│       ├── drawing.py
│       ├── field.py
│       ├── form.py
│       ├── formatting.py
│       ├── hparam.py
│       ├── hwpobject.py
│       ├── page_section.py
│       ├── print_export.py
│       ├── system.py
│       ├── table.py
│       ├── text.py
│       └── utility.py
├── scripts/
│   ├── hwp_bridge.ps1   # PowerShell COMブリッジディスパッチャー
│   └── handlers/        # 12のハンドラーモジュール
│       ├── document.ps1
│       ├── text.ps1
│       ├── table.ps1
│       ├── style_format.ps1
│       ├── action.ps1
│       ├── cursor_selection.ps1
│       ├── field.ps1
│       ├── draw_object.ps1
│       ├── form_control.ps1
│       ├── document_info.ps1
│       ├── print_export.ps1
│       ├── utility.ps1
│       └── hwpobject_methods.ps1
├── tests/
│   ├── test_bridge.py   # ブリッジの単体テスト
│   ├── test_commands.py # コマンドビルダーの単体テスト
│   └── test_server.py   # サーバーツールの単体テスト
└── pyproject.toml

🔧 技術詳細

PythonのMCPサーバーは、HWP COMオブジェクトをホストするPowerShellサブプロセスを管理します。LLMはMCPサーバーを通じて、PowerShellブリッジを経由してHWP COM APIにアクセスします。

開発

uv pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/

制限事項

• Windowsのみ：HWP COM APIはWindowsでのみ動作します。
• 한글が必要：한컴오피스 한글をインストールする必要があります。
• バイナリHWPのみ：HWPX（XMLベース）には別のサーバーが必要です。

📄 ライセンス

MIT