Hwp MCP

🚀 HWP MCP 服務器

HWP MCP 服務器藉助 HWP COM API，使大語言模型（LLMs）能夠讀取和修改二進制 HWP（韓文字處理軟件文檔）文件。

🚀 快速開始

運行 MCP 服務器

python -m hwp_mcp.server

Claude 桌面配置

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

✨ 主要特性

• 支持大語言模型通過 HWP COM API 讀取和修改二進制 HWP 文檔。
• 提供豐富的工具集，涵蓋文檔管理、讀寫、格式設置、表格操作等多個方面。

📦 安裝指南

uv pip install -e .

💻 使用示例

基礎用法

# 運行 MCP 服務器
python -m hwp_mcp.server

📚 詳細文檔

MCP 工具（140 個）

文檔管理（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

開發

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

🔧 技術細節

Python MCP 服務器管理一個長期運行的 PowerShell 子進程，該子進程託管 HWP COM 對象。架構如下：

LLM ↔ MCP Server (Python/FastMCP) ↔ PowerShell Bridge (JSON stdin/stdout) ↔ HWP COM API ↔ 한글

📄 許可證

本項目採用 MIT 許可證。

⚠️ 侷限性

• 僅支持 Windows：HWP COM API 僅在 Windows 系統上可用。
• 需要安裝韓文字處理軟件：必須安裝 한컴오피스 한글。
• 僅支持二進制 HWP 文件：基於 XML 的 HWPX 文件需要單獨的服務器。