Atlas / MCP servers / dayoooun / HWPX

HWPXCAUTION

Name: HWPX
Author: dayoooun

mcp/dayoooun/hwpx

MCP server by dayoooun · Audited 2026-10-08

⚑ Report / re-scan Source ↗

한글 문서(HWPX)를 읽고 쓰는 MCP 서버 — 125개 도구. npm: @kimdayoun/hwpx-mcp

Verdict

CAUTION

Grade

Trust score

89 /100

Exposed tools

118 62r · 46w · 10d

Transport

stdio

License

MIT

Stars

Overview

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

[](https://github.com/Dayoooun/hwpx-mcp) [](https://github.com/mjyoo2/hwp-extension)

🚀 Original 프로젝트를 Fork하여 안정성과 기능을 대폭 개선한 버전입니다.

AI 도구(Claude 등)와 연동하여 한글(HWPX) 문서를 자동으로 편집할 수 있는 MCP(Model Context Protocol) 서버입니다.

🌍 Cross-Platform Support

모든 운영체제에서 작동합니다!

왜 가능한가요? HWPX 파일은 ZIP + XML 구조입니다. 한글 프로그램 없이도 Node.js만으로 완벽하게 읽고 쓸 수 있습니다. *LibreOffice는 HWPX를 제한적으로 지원합니다. 완벽한 호환을 위해 한컴오피스 사용을 권장합니다.

✨ Enhanced Features (개선된 기능)

원본 프로젝트 대비 다음과 같은 핵심 문제들을 해결했습니다:

🔧 Critical Bug Fixes

🛠 Technical Improvements

Atomic File Writing (원자적 파일 쓰기)
임시 파일 → ZIP 검증 → 원자적 이동
저장 중 오류 발생해도 원본 파일 보호

Smart Lineseg Reset (스마트 줄 레이아웃 초기화)
텍스트 수정 시 lineseg 자동 초기화
한글 프로그램이 열 때 자동으로 줄바꿈 재계산
텍스트 겹침 현상 완전 해결

Depth-based XML Parsing (깊이 기반 XML 파싱)
기존 lazy regex의 중첩 구조 오인식 문제 해결
복잡한 테이블(중첩 테이블, subList 등) 완벽 지원

Complete Style Preservation (스타일 완전 보존)
charPr, spacing 등 원본 스타일 100% 유지
불완전한 직렬화 로직 제거로 데이터 무결성 보장

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

Read from source at commit 5d6917ca7195OBSERVED · 2026-10-08

Connect

Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.

claude-code

claude mcp add hwpx-editor -- npx -y [email protected]

claude-desktop

{
  "mcpServers": {
    "hwpx-editor": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ]
    }
  }
}

Exposed tools (118)

62 read · 46 write · 10 destructive. Blast radius: 10 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.

Tool	Risk	Description
`analyze_xml`	read	Analyze document XML for issues like tag imbalance, malformed elements, etc. Useful for diagnosing save failures.
`append_text_to_paragraph`	read	Append text to an existing paragraph (HWPX only)
`apply_style`	write	Apply a named style to a paragraph (HWPX only)
`batch_fill_table`	read	Fill multiple table cells at once from a 2D array. Perfect for: - Filling data tables from CSV/JSON - Batch updating table content - Template form filling Example: batch_fill_table({ data: [ [
`batch_replace`	read	Perform multiple text replacements at once (HWPX only)
`close_document`	read	Close an open document
`copy_paragraph`	read	Copy a paragraph to another location (HWPX only)
`copy_table`	read	Copy a table to another location (HWPX only). Preserves original and generates new IDs for the copy. Uses strict validation.
`create_document`	write	Create a new empty HWPX document. Pass file_path to fix where save_document will write it; otherwise you must pass output_path to save_document.
`delete_image`	destructive	Delete an image from the document (HWPX only)
`delete_memo`	destructive	Delete a memo/comment (HWPX only)
`delete_paragraph`	destructive	Delete a paragraph (HWPX only)
`delete_section`	destructive	Delete a section (HWPX only)
`delete_table`	destructive	Delete an entire table from the document (HWPX only)
`delete_table_column`	destructive	Delete a column from a table (HWPX only)
`delete_table_row`	destructive	Delete a row from a table. If the table has only 1 row, deletes the entire table (HWPX only)
`export_to_html`	read	Export document to HTML file
`export_to_text`	read	Export document to plain text file
`fill_by_path`	read	⭐ RECOMMENDED for template work! Fill multiple cells using path-based addressing. jkf87-style path format:
`find_cell_by_label`	read	🔍 Find table cells by label text and get the adjacent cell position. Perfect for Korean documents with
`find_empty_tables`	read	Find tables that are empty or contain only placeholder text (dashes, bullets, numbers only)
`find_insert_position_after_header`	write	Find the right insertion position after text. Searches both independent paragraphs AND table cell contents by default. IMPORTANT - Check
`find_insert_position_after_table`	write	Find the right insertion position AFTER a specific table (OUTSIDE the table). Returns section_index and insert_after value for use with insert_image/render_mermaid. NOTE: This inserts AFTER the table, not inside it. To insert an image INSIDE a table cell, use insert_image_in_cell directly.
`find_paragraph_by_text`	read	Find paragraphs containing specific text. Returns element indices with surrounding context.
`find_table_by_header`	read	Find tables by their header text (partial match, case-insensitive)
`get_bookmarks`	read	Get all bookmarks in the document
`get_cell_context`	read	Get surrounding cells
`get_char_shapes`	read	Get all character shape definitions
`get_chunk_at_offset`	read	📌 Get the chunk containing a specific character offset. Use after finding a position in the index to get the full chunk context.
`get_chunk_context`	read	📄 Get surrounding chunks for expanded context around a specific chunk. After finding a relevant chunk with search_chunks, use this to get additional context by retrieving chunks before and after the target chunk.
`get_column_def`	read	Get column definition for a section
`get_document_metadata`	read	Get document metadata (title, author, dates, etc.)
`get_document_outline`	read	Get document outline - hierarchical structure showing sections, headings, and tables with their positions
`get_document_structure`	read	Get document structure (sections, paragraphs, tables, images count)
`get_document_text`	read	Get all text content from the document
`get_element_index_for_table`	read	Convert a global table index to element index in its section. Use this to find the right position for inserting content near a table.
`get_endnotes`	read	Get all endnotes in the document
`get_equations`	read	Get all equations in the document
`get_footer`	read	Get footer content for a section
`get_footnotes`	read	Get all footnotes in the document
`get_hanging_indent`	read	Get hanging indent value for a paragraph
`get_header`	read	Get header content for a section
`get_hyperlinks`	read	Get all hyperlinks in the document
`get_images`	write	Get all images in the document. For inserting images, see insert_image or insert_image_in_cell.
`get_insert_context`	write	Get context around an element index to verify insertion point. Shows elements before/after.
`get_memos`	read	Get all memos/comments in the document
`get_page_settings`	read	Get page settings (paper size, margins)
`get_para_shapes`	read	Get all paragraph shape definitions
`get_paragraph`	read	Get a specific paragraph with full details
`get_paragraph_style`	read	Get paragraph formatting
`get_paragraphs`	read	Get paragraphs from the document with their text and styles
`get_position_index`	read	📍 Get cached position index (builds if not available). Returns all indexed elements. Use search_position_index for filtered queries.
`get_raw_section_xml`	read	⚠️ DEPRECATED: Use get_section_xml instead. This tool is kept for backward compatibility only.
`get_section_xml`	read	Get raw XML content of a section. Useful for AI-based document manipulation. Returns the complete section XML that can be modified and set back using set_section_xml.
`get_sections`	read	Get all sections in the document
`get_styles`	read	Get all defined styles in the document
`get_table`	read	Get a specific table with full data
`get_table_as_csv`	read	Export table content as CSV format
`get_table_cell`	read	Get content of a specific table cell
`get_table_cell_hanging_indent`	read	Get hanging indent value for a paragraph inside a table cell
`get_tables`	read	Get all tables from the document
`get_tables_by_section`	read	Get all tables within a specific section
`get_tables_summary`	read	Get summary of multiple tables by index range. Returns compact info: header, size, empty status, and content preview.
`get_text_style`	read	Get character formatting of a paragraph
`get_tool_guide`	write	🎯 START HERE! Get recommended tools for your task. Call this FIRST to understand which tools to use. Available workflows: -
`get_word_count`	read	Get word and character count statistics
`insert_bookmark`	write	Insert a bookmark at a specific location (HWPX only)
`insert_ellipse`	write	Insert an ellipse drawing object (HWPX only)
`insert_endnote`	write	Insert an endnote at a specific location (HWPX only)
`insert_equation`	write	Insert an equation (HWPX only)
`insert_footnote`	write	Insert a footnote at a specific location (HWPX only)
`insert_hyperlink`	write	Insert a hyperlink in a paragraph (HWPX only)
`insert_image`	write	Insert an image into the document (HWPX only)
`insert_image_in_cell`	write	📍 Insert an image INSIDE a specific table cell (HWPX only). The image appears inline within the cell content. ⚠️ IMPORTANT: Use this tool (NOT insert_image) when inserting images into table cells! When to use: 1. find_insert_position_after_header returned found_in=
`insert_line`	write	Insert a line drawing object (HWPX only)
`insert_memo`	write	Insert a memo/comment (HWPX only)
`insert_nested_table`	write	Insert a table inside a table cell (nested table, HWPX only)
`insert_paragraph`	write	Insert a new paragraph (HWPX only). Automatically applies hanging indent if text contains a marker like
`insert_rect`	write	Insert a rectangle drawing object (HWPX only)
`insert_section`	write	Insert a new section (HWPX only)
`insert_table`	write	Insert a new table (HWPX only)
`insert_table_column`	write	Insert a new column in a table (HWPX only)
`insert_table_row`	write	Insert a new row in a table (HWPX only)
`invalidate_reading_cache`	destructive	🔄 Clear cached chunks and position index. Call this after modifying the document to ensure fresh data on next read operation.
`list_open_documents`	read	List all currently open documents
`merge_cells`	write	Merge multiple table cells into a single cell (HWPX only). The top-left cell becomes the master cell with increased colSpan/rowSpan.
`move_paragraph`	write	Move a paragraph to another location (HWPX only)
`move_table`	write	Move a table to another location (HWPX only). Uses XML-based approach for accurate structure preservation with strict validation.
`open_document`	read	Open an HWPX or HWP document for reading and editing
`redo`	read	Redo the last undone change(s). Supports multiple redo with count parameter.
`remove_hanging_indent`	destructive	Remove hanging indent from a paragraph (HWPX only)
`remove_table_cell_hanging_indent`	destructive	Remove hanging indent from a paragraph inside a table cell (HWPX only)
`render_mermaid_in_cell`	write	📍 Render a Mermaid diagram and insert it INSIDE a specific table cell (HWPX only). Uses mermaid.ink API. ⚠️ IMPORTANT: Use this tool (NOT render_mermaid) when inserting diagrams into table cells! When to use: 1. find_insert_position_after_header returned found_in=
`repair_xml`	read	Attempt to repair XML issues in a section. Removes orphan closing tags and fixes table structure.
`replace_text`	read	Find and replace text throughout the ENTIRE document (HWPX only). ⚠️ This searches ALL paragraphs and table cells in the document. When to use: - Bulk replacement (e.g., change
`replace_text_in_cell`	read	Replace text within a specific table cell (HWPX only). More targeted than replace_text.
`save_document`	write	Save the document (HWPX only). Supports backup creation and integrity verification.
`search_position_index`	read	🔎 Search position index by text and/or element type. Filter the position index to find specific headings, paragraphs, or tables by their text content.
`search_text`	read	Search for text in the document (includes table cells by default)
`set_auto_hanging_indent`	write	Automatically set hanging indent based on detected marker in paragraph text (HWPX only). Detects markers like
`set_cell_properties`	write	Set table cell properties (HWPX only)
`set_column_def`	write	Set column definition for a section (HWPX only)
`set_document_metadata`	write	Set document metadata (HWPX only)
`set_footer`	write	Set footer content for a section (HWPX only)
`set_hanging_indent`	write	Set hanging indent with MANUAL pt value (HWPX only). 💡 In most cases, use set_auto_hanging_indent instead - it automatically detects markers and calculates the correct indent. Use this manual version only when: - You need a specific indent value (e.g., exactly 20pt) - Auto-detection doesn
`set_header`	write	Set header content for a section (HWPX only)
`set_page_settings`	write	Set page settings (HWPX only)
`set_paragraph_style`	write	Apply paragraph formatting (HWPX only)
`set_raw_section_xml`	write	⚠️ DEPRECATED: Use set_section_xml instead. This tool is kept for backward compatibility only.
`set_section_xml`	write	Set (replace) raw XML content of a section (HWPX only). WARNING: This completely replaces the section XML. The XML must be valid HWPML format. Use get_section_xml first to get the current structure, modify it, then set it back.
`set_table_cell_auto_hanging_indent`	write	Automatically set hanging indent on a paragraph inside a table cell based on detected marker (HWPX only). Detects markers like
`set_table_cell_hanging_indent`	write	Set hanging indent on a paragraph inside a table cell (HWPX only). Hanging indent pulls the first line left while indenting the rest of the lines.
`set_text_style`	write	Apply character formatting to a paragraph run (HWPX only)
`split_cell`	read	Split a merged table cell back into individual cells (HWPX only). Only works on cells with colSpan > 1 or rowSpan > 1.
`undo`	read	Undo the last change(s). Supports multiple undo with count parameter.
`update_image_size`	write	Update the size of an existing image (HWPX only)
`update_paragraph_text`	write	Update paragraph text content (HWPX only)
`update_table_cell`	write	Update content of a table cell (HWPX only)

Trust audit

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

Layer	What it checks	Result
L0	Provenance & inventory	WARN
L1	Static analysis of the code	PASS
L2	Instruction surface (what it tells the agent)	PASS
L3	Class-specific surface	WARN
L4	Behavioural (sandbox)	SKIPPED

What the source does

Filesystem: declared (2 observation(s))
Network: declared (2 observation(s))
Shell: declared (2 observation(s))
Dependencies: not all pinned
Secrets in source: none-found

Findings (11)

MEDIUMInventory / provenance · inv.binary · CWE-1104

mcp-server/test-output/text-duplication-test.hwpx.bak

text-duplication-test.hwpx.bak

Why it matters. a compiled or binary member cannot be reviewed from source

Fix. ship source, or explain the binary in the README

MEDIUMInventory / provenance · inv.binary · CWE-1104

test-output/test1.hwpx.bak

test1.hwpx.bak

Why it matters. a compiled or binary member cannot be reviewed from source

Fix. ship source, or explain the binary in the README

MEDIUMFilesystem / path · mcp.destructive_tools · CWE-22, CWE-59

delete_image, delete_memo, delete_paragraph, delete_section, delete_table, delete_table_column, delete_table_row, invalidate_reading_cache, remove_hanging_indent, remove_table_cell_hanging_indent

Why it matters. 10 tool(s) can delete or overwrite

Fix. prefer a read-only mode or scoped tokens; the page states the blast radius

LOWInventory / provenance · inv.hidden_file · CWE-1104

.vscodeignore

.vscodeignore

Why it matters. hidden member outside the usual dotfiles

Fix. review its purpose