HWPX MCP Server

$git clone https://github.com/Dayoooun/hwpx-mcp.git && cd hwpx-mcp/mcp-server && npm install && npm run build
README.md

Read, create, and edit Korean HWPX documents with advanced support.

HWPX MCP Server - Enhanced Edition

πŸš€ Original ν”„λ‘œμ νŠΈλ₯Ό Forkν•˜μ—¬ μ•ˆμ •μ„±κ³Ό κΈ°λŠ₯을 λŒ€ν­ κ°œμ„ ν•œ λ²„μ „μž…λ‹ˆλ‹€.

AI 도ꡬ(Claude λ“±)와 μ—°λ™ν•˜μ—¬ ν•œκΈ€(HWPX) λ¬Έμ„œλ₯Ό μžλ™μœΌλ‘œ νŽΈμ§‘ν•  수 μžˆλŠ” MCP(Model Context Protocol) μ„œλ²„μž…λ‹ˆλ‹€.

🌍 Cross-Platform Support

λͺ¨λ“  μš΄μ˜μ²΄μ œμ—μ„œ μž‘λ™ν•©λ‹ˆλ‹€!

OS MCP μ„œλ²„ HWPX νŽΈμ§‘ κ²°κ³Όλ¬Ό 확인
βœ… Windows βœ… βœ… ν•œμ»΄μ˜€ν”ΌμŠ€
βœ… macOS βœ… βœ… ν•œμ»΄μ˜€ν”ΌμŠ€ Mac
βœ… Linux βœ… βœ… ν•œμ»΄μ˜€ν”ΌμŠ€ Linux / LibreOffice*

μ™œ κ°€λŠ₯ν•œκ°€μš”? HWPX νŒŒμΌμ€ ZIP + XML κ΅¬μ‘°μž…λ‹ˆλ‹€. ν•œκΈ€ ν”„λ‘œκ·Έλž¨ 없이도 Node.js만으둜 μ™„λ²½ν•˜κ²Œ 읽고 μ“Έ 수 μžˆμŠ΅λ‹ˆλ‹€.

*LibreOfficeλŠ” HWPXλ₯Ό μ œν•œμ μœΌλ‘œ μ§€μ›ν•©λ‹ˆλ‹€. μ™„λ²½ν•œ ν˜Έν™˜μ„ μœ„ν•΄ ν•œμ»΄μ˜€ν”ΌμŠ€ μ‚¬μš©μ„ ꢌμž₯ν•©λ‹ˆλ‹€.

✨ Enhanced Features (κ°œμ„ λœ κΈ°λŠ₯)

원본 ν”„λ‘œμ νŠΈ λŒ€λΉ„ λ‹€μŒκ³Ό 같은 핡심 λ¬Έμ œλ“€μ„ ν•΄κ²°ν–ˆμŠ΅λ‹ˆλ‹€:

πŸ”§ Critical Bug Fixes

문제 원본 μƒνƒœ κ°œμ„  ν›„
ν…Œμ΄λΈ” μ €μž₯ μ‹€νŒ¨ μ…€ μˆ˜μ • ν›„ μ €μž₯해도 변경사항 사라짐 βœ… μ™„λ²½ν•˜κ²Œ μ €μž₯됨
ν…μŠ€νŠΈ κ²ΉμΉ¨ ν˜„μƒ μ €μž₯ ν›„ ν•œκΈ€μ—μ„œ μ—΄λ©΄ κΈ€μžκ°€ 겹쳐 ν‘œμ‹œ βœ… 정상 ν‘œμ‹œ
파일 손상 μ €μž₯ μ‹œ 가끔 파일이 손상됨 βœ… μ›μžμ  μ“°κΈ°λ‘œ 100% μ•ˆμ „
닀쀑 μ…€ 손상 같은 행에 μ—¬λŸ¬ μ…€ μˆ˜μ • μ‹œ XML 손상 βœ… 인덱슀 κ΄€λ¦¬λ‘œ μ•ˆμ „
μžκ°„/쀄간격 손싀 μ €μž₯ ν›„ μŠ€νƒ€μΌ 정보 μœ μ‹€ βœ… λͺ¨λ“  μŠ€νƒ€μΌ 보쑴

πŸ›  Technical Improvements

  1. Atomic File Writing (μ›μžμ  파일 μ“°κΈ°)

    • μž„μ‹œ 파일 β†’ ZIP 검증 β†’ μ›μžμ  이동
    • μ €μž₯ 쀑 였λ₯˜ λ°œμƒν•΄λ„ 원본 파일 보호

  2. Smart Lineseg Reset (슀마트 쀄 λ ˆμ΄μ•„μ›ƒ μ΄ˆκΈ°ν™”)

    • ν…μŠ€νŠΈ μˆ˜μ • μ‹œ lineseg μžλ™ μ΄ˆκΈ°ν™”
    • ν•œκΈ€ ν”„λ‘œκ·Έλž¨μ΄ μ—΄ λ•Œ μžλ™μœΌλ‘œ μ€„λ°”κΏˆ μž¬κ³„μ‚°
    • ν…μŠ€νŠΈ κ²ΉμΉ¨ ν˜„μƒ μ™„μ „ ν•΄κ²°

  3. Depth-based XML Parsing (깊이 기반 XML νŒŒμ‹±)

    • κΈ°μ‘΄ lazy regex의 쀑첩 ꡬ쑰 μ˜€μΈμ‹ 문제 ν•΄κ²°
    • λ³΅μž‘ν•œ ν…Œμ΄λΈ”(쀑첩 ν…Œμ΄λΈ”, subList λ“±) μ™„λ²½ 지원

  4. Complete Style Preservation (μŠ€νƒ€μΌ μ™„μ „ 보쑴)

    • charPr, spacing λ“± 원본 μŠ€νƒ€μΌ 100% μœ μ§€
    • λΆˆμ™„μ „ν•œ 직렬화 둜직 제거둜 데이터 무결성 보μž₯

  5. Safe Multi-Cell Updates (μ•ˆμ „ν•œ 닀쀑 μ…€ μ—…λ°μ΄νŠΈ)

    • 같은 ν–‰(row)의 μ—¬λŸ¬ 셀을 λ™μ‹œμ— μˆ˜μ •ν•΄λ„ μ•ˆμ „
    • 행별 κ·Έλ£Ήν™” + μ—­μˆœ 처리둜 인덱슀 손상 방지

πŸ“¦ Installation

1. MCP μ„œλ²„ μ„€μΉ˜

git clone https://github.com/Dayoooun/hwpx-mcp.git
cd hwpx-mcp/mcp-server
npm install
npm run build

2. MCP ν΄λΌμ΄μ–ΈνŠΈ μ„€μ •

μ•„λž˜μ—μ„œ μ‚¬μš©ν•˜λŠ” ν΄λΌμ΄μ–ΈνŠΈλ₯Ό μ„ νƒν•˜μ„Έμš”.

πŸ–₯️ Claude Desktop

μ„€μ • 파일 μœ„μΉ˜:

OS 경둜
Windows %APPDATA%\Claude\claude_desktop_config.json
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json

μ„€μ • λ‚΄μš©:

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["C:/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

⚠️ Windowsμ—μ„œλŠ” κ²½λ‘œμ— \\ λ˜λŠ” / μ‚¬μš© (예: C:/Users/username/hwpx-mcp/...)

πŸ’» Claude Code (CLI)

방법 1: ν”„λ‘œμ νŠΈλ³„ μ„€μ • (.mcp.json νŒŒμΌμ„ ν”„λ‘œμ νŠΈ λ£¨νŠΈμ— 생성)

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

방법 2: μ „μ—­ μ„€μ • (~/.claude/settings.json)

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

방법 3: CLI λͺ…λ Ήμ–΄λ‘œ μΆ”κ°€

claude mcp add hwpx-mcp node /path/to/hwpx-mcp/mcp-server/dist/index.js
πŸ”· Cursor

μ„€μ • 파일: ~/.cursor/mcp.json (μ—†μœΌλ©΄ 생성)

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

λ˜λŠ” Cursor Settings > MCP μ—μ„œ 직접 μΆ”κ°€ κ°€λŠ₯

πŸ†š VS Code (MCP ν™•μž₯ μ‚¬μš© μ‹œ)

μ„€μ • 파일: .vscode/mcp.json (ν”„λ‘œμ νŠΈ 폴더 λ‚΄)

{
  "servers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["${workspaceFolder}/../hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

${workspaceFolder} λ³€μˆ˜λ₯Ό ν™œμš©ν•˜λ©΄ μƒλŒ€ 경둜 지정 κ°€λŠ₯

πŸ› οΈ 기타 MCP ν΄λΌμ΄μ–ΈνŠΈ

일반적인 MCP μ„€μ • ν˜•μ‹:

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

경둜 μ˜ˆμ‹œ:

OS 경둜 μ˜ˆμ‹œ
Windows C:/Users/username/hwpx-mcp/mcp-server/dist/index.js
macOS /Users/username/hwpx-mcp/mcp-server/dist/index.js
Linux /home/username/hwpx-mcp/mcp-server/dist/index.js

3. μ„€μΉ˜ 확인

ν΄λΌμ΄μ–ΈνŠΈ μž¬μ‹œμž‘ ν›„ MCP 도ꡬ λͺ©λ‘μ—μ„œ hwpx-mcp μ„œλ²„μ™€ 77개 도ꡬ가 ν‘œμ‹œλ˜λ©΄ 성곡!

πŸ”Œ MCP Tools (77개)

πŸ“ λ¬Έμ„œ 관리 (Document Management) - 5개

Tool μ„€λͺ… μ£Όμš” νŒŒλΌλ―Έν„°
create_document μƒˆ 빈 HWPX λ¬Έμ„œ 생성 title?, creator?
open_document HWPX λ¬Έμ„œ μ—΄κΈ° file_path
close_document μ—΄λ¦° λ¬Έμ„œ λ‹«κΈ° doc_id
save_document λ¬Έμ„œ μ €μž₯ (λ°±μ—…/무결성 검증 지원) doc_id, output_path?, create_backup?, verify_integrity?
list_open_documents ν˜„μž¬ μ—΄λ¦° λ¬Έμ„œ λͺ©λ‘ 쑰회 -

πŸ“„ λ¬Έμ„œ 정보 (Document Info) - 5개

Tool μ„€λͺ… μ£Όμš” νŒŒλΌλ―Έν„°
get_document_text λ¬Έμ„œ 전체 ν…μŠ€νŠΈ μΆ”μΆœ doc_id
get_document_structure λ¬Έμ„œ ꡬ쑰 쑰회 (μ„Ήμ…˜/단락/ν…Œμ΄λΈ”/이미지 수) doc_id
get_document_metadata 메타데이터 쑰회 (제λͺ©, μ €μž, λ‚ μ§œ λ“±) doc_id
set_document_metadata 메타데이터 μˆ˜μ • doc_id, title?, creator?, subject?, description?
get_word_count κΈ€μžμˆ˜/λ‹¨μ–΄μˆ˜ 톡계 doc_id

Tools (10)

create_documentCreate a new empty HWPX document
open_documentOpen an existing HWPX document
close_documentClose an open document
save_documentSave document with backup and integrity verification support
list_open_documentsList all currently open documents
get_document_textExtract all text from the document
get_document_structureGet document structure including sections, paragraphs, tables, and images
get_document_metadataRetrieve metadata like title, author, and dates
set_document_metadataModify document metadata
get_word_countGet statistics for character and word counts

Configuration

claude_desktop_config.json
{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

Try it

β†’Open the HWPX file at 'C:/Documents/report.hwpx' and tell me the total word count.
β†’Create a new HWPX document titled 'Meeting Minutes' with me as the creator.
β†’Extract all the text from the currently open HWPX document.
β†’Update the metadata of document ID 1 to set the subject to 'Quarterly Review'.
β†’Save the current HWPX document to a new path 'D:/Backups/report_v2.hwpx' and verify its integrity.

Frequently Asked Questions

What are the key features of HWPX MCP Server?

Atomic File Writing to prevent document corruption during saves.. Smart Lineseg Reset to automatically fix text overlapping issues in HWPX.. Depth-based XML Parsing for accurate handling of nested tables and complex structures.. Complete Style Preservation for character properties and spacing.. Cross-platform support for Windows, macOS, and Linux without requiring Hancom Office installed..

What can I use HWPX MCP Server for?

Automated editing of Korean HWPX documents using AI models like Claude.. Extracting structured data and text from legacy HWPX files for analysis.. Generating official Korean reports programmatically with correct styling.. Batch processing and metadata management of HWPX document libraries..

How do I install HWPX MCP Server?

Install HWPX MCP Server by running: git clone https://github.com/Dayoooun/hwpx-mcp.git && cd hwpx-mcp/mcp-server && npm install && npm run build

What MCP clients work with HWPX MCP Server?

HWPX MCP Server works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Use HWPX MCP Server with Conare

Manage MCP servers visually, upload persistent context, and never start from zero with Claude Code & Codex.

Try Free

Related MCP Servers

Personal Knowledge MCP Server
Indexes local and enterprise documents to provide a unified personal knowledge base.
file-management34 stars
md2doc
Convert Markdown text to DOCX format using an external conversion service
file-management6 stars
Obsidian Dictionary
Manage a technical terminology glossary within an Obsidian vault
file-management3 stars
macOS MCP Server
MCP server for macOS system operations: file dialogs, clipboard, notifications, Finder integration.
file-management1 stars
Nipoppy MCP Server
A Model Context Protocol (MCP) interface for the Nipoppy neuroimaging dataset framework.
file-management
AI Workspace MCP Server
Secure workspace for AI file management and Python execution.
file-management