Hwp Automation

HWP MCP服务器

用于自动化韩文（HWP）文档的Model Context Protocol（MCP）服务器

概要

该项目是一款MCP服务器，允许您通过Claude Desktop自动执行韩文和计算机的HWP文档。

主要功能

• ✅ 类型安全性：基于Idris2格式规范的状态管理
• ✅ 验证状态转换：自动管理文档生命周期（Closed→Opened→Modified→Saved）
• ✅ COM自动化：通过pywin32实现韩文COM API集成
• ✅ MCP标准：与Claude Desktop完全兼容

必要条件

• 操作系统：Windows（需要韩文程序）
• python：3.10以上
• 韩文：需要安装韩文和计算机文字处理器
• 包管理器：建议uv

安装

1.uv安装（推荐）

# uv 설치 (없는 경우)
pip install uv

# 프로젝트 의존성 설치
uv pip install -e .

2.使用pip安装

pip install -e .

Claude桌面设置

claude_desktop_config.json 将以下内容添加到文件：

视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hwp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\YourName\\Projects\\HwpAutomation",
        "run",
        "python",
        "-m",
        "src.server"
      ]
    }
  }
}

可用工具（Tools）

1. hwp_create_document

创建新的韩文文档

상태 전환: Closed → Opened
파라미터: 없음

2. hwp_open_document

打开现有的韩文文档

상태 전환: Closed → Opened
파라미터:
  - path (string): 열 파일 경로

3. hwp_close_document

关闭当前文档

상태 전환: Opened → Closed
파라미터: 없음

4. hwp_save_document

保存文档

상태 전환: Modified → Saved
파라미터: 없음

5. hwp_insert_text

插入文本

상태 전환: Opened → Modified
파라미터:
  - text (string): 삽입할 텍스트

6. hwp_create_table

创建表格

상태 전환: Opened → Modified
파라미터:
  - rows (integer): 행 개수
  - cols (integer): 열 개수

7. hwp_get_document_state

查看当前文档状态

파라미터: 없음
반환: 문서 상태 및 경로 정보

使用示例

Claude Desktop可以要求：

새 한글 문서를 만들고 "안녕하세요, MCP!"라는 텍스트를 넣어주세요.
그리고 3x3 표를 하나 만들어주세요.

Claude自动：

1. hwp_create_document 呼叫
2. hwp_insert_text 呼叫
3. hwp_create_table 呼叫

体系结构

目录结构

HwpAutomation/
├── Specs/
│   └── HwpMCP.idr          # Idris2 형식 명세
├── HwpBooks/
│   └── ActionTable_2504.pdf # 한글 Action 참조 문서
├── src/
│   ├── __init__.py
│   ├── types.py            # 타입 정의 (Idris 스펙 기반)
│   ├── hwp_client.py       # HWP COM 클라이언트
│   ├── tools.py            # MCP 도구 정의
│   └── server.py           # MCP 서버 진입점
├── pyproject.toml
├── README.md
└── claude.md               # 개발 로그

状态图

Closed ──create/open──> Opened ──insert_text/create_table──> Modified
  ↑                        ↓                                      ↓
  └────── close ───────────┘                                      │
                                                                  │
                                         Saved <───── save ───────┘

开发

编译Idris2规格

cd Specs
idris2 HwpMCP.idr -o build/hwp_mcp

类型验证

mypy src/

测试

pytest tests/

参考资料

• MCP规范
• 克劳德桌面MCP
• HWP COM API： HwpBooks/ActionTable_2504.pdf
• Idris2规范： Specs/HwpMCP.idr

许可证

MIT许可证

贡献

欢迎发布和Pull Request！

故障排除

如果HWP程序无法打开

• 检查是否安装了韩文和计算机文字处理器
• 仅适用于Windows

COM初始化错误

uv pip install --upgrade pywin32
python -m win32com.client.makepy "HWPFrame.HwpObject"

权限错误

• 以管理员权限运行
• 确认韩文程序未在其他进程中使用