한글 mcp hwpx MCP Server
MCP ServerFree<p align="center"> <h1 align="center">📄 hwpx-mcp-server</h1> <p align="center"> <strong>한글(HWPX) 문서를 AI로 자동화하는 MCP 서버</strong> </p> <p align="center"> 한글 워드프로세서 없이 · 순수 파이썬 · 크로스 플랫폼 </p> <p align="center"> <a href="https://pypi.org/project/hwpx-mcp-server/"><img src="https:
Capabilities25 decomposed
stateless-hwpx-document-reading-with-context-preservation
Medium confidenceReads HWPX (Open XML-based Korean word processor format) documents without requiring persistent state or the native Hangeul application, using pure Python XML parsing via python-hwpx library. Each tool invocation explicitly specifies the filename, enabling stateless operation across distributed MCP clients. The implementation parses OPC (Open Packaging Convention) package structure to extract document metadata, text content, and structural hierarchy (sections, paragraphs, tables) with character-level position tracking for context-aware retrieval.
Implements stateless document reading where every tool call includes explicit filename parameter, eliminating session state management and enabling safe concurrent access from multiple MCP clients. Uses OPC package parsing to directly access document.xml without requiring Hangeul application or binary format reverse-engineering.
Eliminates Windows/Hangeul dependency that COM-based automation requires, while maintaining full cross-platform support (Windows/macOS/Linux) with pure Python implementation.
hwpx-to-markdown-conversion-with-chunking
Medium confidenceConverts HWPX documents to Markdown format with configurable output strategies (full document or chunked by section/paragraph). The conversion pipeline parses document structure, maps heading levels to Markdown syntax (#, ##, ###), preserves table formatting as Markdown tables, and optionally splits output into chunks based on character limits or structural boundaries. Supports both file-based input (filename) and payload-based input (base64-encoded HWPX or HTTPS URL), enabling both local and remote document processing.
Supports dual input modes (file path + payload-based base64/URL) with identical tool interface, enabling both local document processing and remote document fetching. Chunking respects document structure (section/paragraph boundaries) rather than naive character splitting, preserving semantic coherence for LLM processing.
Faster than Hangeul application export because it uses direct XML parsing; more flexible than pandoc because it understands HWPX-specific structure (sections, custom styles) natively.
document-copying-with-safety-validation
Medium confidenceCreates a safe copy of HWPX documents with validation to ensure copy integrity. The copy operation reads source document, validates structure, writes to destination path, and verifies copy completeness. Useful for creating backups before destructive operations or generating document variants.
Validates copy integrity by comparing source and destination structure, ensuring safe document duplication before risky operations.
More reliable than OS-level file copy because it validates HWPX structure integrity; enables safe document variant generation.
table-creation-with-configurable-dimensions
Medium confidenceCreates new tables in HWPX documents with specified row and column counts. The table creation engine inserts a table element at specified paragraph index, initializes cells with empty content, and optionally applies basic formatting (header row styling). Tables are fully editable after creation via cell-level operations.
Creates properly structured HWPX tables with configurable dimensions and optional header styling, enabling data-driven document generation.
More flexible than template-based tables because dimensions are configurable; more reliable than manual table insertion because it maintains HWPX structure integrity.
table-cell-text-modification-with-range-support
Medium confidenceModifies text content in table cells by table index, row, and column coordinates. The cell modification engine locates target cell, replaces content while preserving cell formatting, and supports batch operations for multiple cell updates. Enables data population in pre-created tables.
Provides cell-level table editing with coordinate-based access, enabling precise data population in tables.
More granular than document-level editing because it operates at cell level; enables efficient data-driven table population.
table-cell-merging-and-splitting-for-complex-layouts
Medium confidenceManages table cell merging and splitting operations to create complex table layouts. The merge operation combines adjacent cells horizontally or vertically, and the split operation divides merged cells back into individual cells. Supports both single-cell and range-based operations.
Supports both cell merging and splitting with directional control, enabling creation of complex table layouts programmatically.
More flexible than fixed table structures because it allows dynamic layout adjustments; enables sophisticated report generation with merged headers and grouped data.
table-formatting-with-header-styling
Medium confidenceApplies basic formatting to tables including header row styling, border configuration, and cell alignment. The formatting engine applies predefined style templates to table elements, enabling consistent table appearance across documents.
Provides template-based table formatting that applies consistent styling across tables, enabling professional document appearance.
More convenient than manual cell-by-cell formatting because it applies templates; ensures consistent table appearance across documents.
text-range-formatting-with-multiple-attributes
Medium confidenceApplies formatting attributes (bold, italic, underline, color, font size, font family) to text ranges within paragraphs. The formatting engine locates target text, applies formatting attributes to underlying XML runs, and preserves existing formatting for non-targeted attributes. Supports both single-range and multi-range formatting operations.
Applies multiple formatting attributes simultaneously to text ranges while preserving existing formatting on non-targeted attributes.
More flexible than paragraph-level formatting because it operates at text range level; enables selective emphasis within paragraphs.
custom-style-creation-and-management
Medium confidenceCreates and manages custom paragraph and character styles in HWPX documents. The style creation engine defines new styles with configurable properties (font, size, color, spacing), adds styles to document style sheet, and enables reuse across document. Supports style inheritance and override.
Enables creation of custom styles that are stored in document style sheet and reusable across document, supporting organizational style standards.
More flexible than predefined styles because custom styles can be tailored to organizational requirements; enables consistent branding across documents.
document-style-listing-and-inspection
Medium confidenceLists all available styles in a document (paragraph and character styles) with detailed property inspection. The style listing engine enumerates styles from document style sheet, extracts style properties (font, size, color, spacing), and returns structured style information for inspection or reuse.
Provides comprehensive style listing with property extraction, enabling style-aware document generation and analysis.
More informative than simple style enumeration because it includes detailed property information; enables intelligent style selection for generated content.
opc-package-introspection-with-part-enumeration
Medium confidenceInspects OPC (Open Packaging Convention) package structure of HWPX files, enumerating all package parts (document.xml, styles.xml, numbering.xml, etc.) with metadata. Available only in advanced mode (HWPX_MCP_ADVANCED=1). The introspection engine reads package manifest, lists parts with content types and relationships, enabling low-level document analysis.
Provides low-level OPC package introspection for advanced users, enabling direct access to document internals for customization or debugging.
More detailed than high-level document analysis because it exposes package structure; enables advanced customization not possible through standard tools.
opc-part-xml-and-text-extraction
Medium confidenceExtracts raw XML or text content from specific OPC package parts (document.xml, styles.xml, etc.). Available only in advanced mode (HWPX_MCP_ADVANCED=1). The extraction engine locates target part, reads content, and returns either raw XML or extracted text depending on part type.
Provides direct access to OPC part XML content for advanced users, enabling custom XML transformations and low-level document manipulation.
More powerful than high-level APIs because it exposes raw XML; enables custom transformations not possible through standard tools.
hwpx-to-html-conversion-with-semantic-preservation
Medium confidenceConverts HWPX documents to HTML5 with semantic tag preservation (headings, sections, tables, lists). The conversion engine maps HWPX paragraph styles to HTML semantic elements, preserves table structure with proper thead/tbody/tfoot, and handles image references (with configurable image policy: omitted, base64-embedded, or URL-referenced). Supports chunked output with section-aware boundaries, enabling HTML fragments suitable for web embedding or LLM processing.
Generates semantic HTML5 with proper heading hierarchy and section structure derived from HWPX paragraph styles, rather than flat div-based output. Implements configurable image policy (omitted/base64/URL) to balance payload size vs. content completeness.
Produces semantic HTML suitable for accessibility and SEO, unlike simple regex-based converters; preserves document structure better than generic XML-to-HTML transformations because it understands HWPX style semantics.
xml-element-search-by-tag-and-attribute
Medium confidenceSearches for XML elements in document parts by tag name or attribute values. Available only in advanced mode (HWPX_MCP_ADVANCED=1). The search engine queries document.xml or other parts using XPath-like patterns, returning matching elements with context.
Provides element-level XML search by tag and attribute, enabling targeted queries on document structure.
More precise than full-document XML parsing because it targets specific elements; enables efficient element-level analysis.
edit-planning-with-preview-and-atomic-application
Medium confidenceProvides a three-step edit workflow: plan_edit (describe desired changes), preview_edit (show what changes will be made), and apply_edit (execute changes atomically). Available only in advanced mode (HWPX_MCP_ADVANCED=1). The edit pipeline enables AI agents to propose changes, review them before application, and apply atomically with rollback capability.
Implements three-step edit workflow (plan → preview → apply) with atomic application, enabling safe document modification with change verification.
More cautious than direct editing because it requires explicit preview and approval; enables AI-driven editing with human oversight.
document-structure-validation-and-integrity-checking
Medium confidenceValidates HWPX document structure for integrity and consistency. Available only in advanced mode (HWPX_MCP_ADVANCED=1). The validation engine checks for structural errors (malformed XML, missing required elements, broken references), reports issues with severity levels, and suggests corrections.
Provides comprehensive structure validation with severity levels and correction suggestions, enabling document quality assurance.
More thorough than simple format checking because it validates structural consistency; enables early detection of issues that may cause rendering problems.
text-convention-linting-for-style-consistency
Medium confidenceLints document text for style consistency violations (spacing, punctuation, naming conventions). Available only in advanced mode (HWPX_MCP_ADVANCED=1). The linting engine scans document paragraphs, checks against configurable style rules (e.g., spacing before punctuation, consistent terminology), and reports violations with suggestions.
Provides text convention linting with configurable rules for style consistency, enabling automated quality assurance for document style.
More specific than generic spell-checking because it focuses on style conventions; enables enforcement of organizational writing standards.
mcp-server-transport-abstraction-with-stdio-and-http
Medium confidenceProvides transport-agnostic MCP server implementation supporting both stdio (default) and streamable HTTP transports. The transport abstraction layer enables the same tool set to be accessed via stdio (for Claude Desktop, Cursor) or HTTP (for remote clients, web-based MCP clients). Transport selection via CLI arguments or environment variables (HWPX_MCP_TRANSPORT, HWPX_MCP_HOST, HWPX_MCP_PORT).
Implements transport abstraction that enables identical tool set to be accessed via stdio or HTTP, supporting diverse deployment scenarios without code duplication.
More flexible than single-transport servers because it supports both stdio and HTTP; enables use in both desktop (Claude) and server (remote) environments.
hwpx-structure-extraction-to-json-with-toc-generation
Medium confidenceExtracts complete HWPX document structure (title, table of contents, sections, paragraphs, tables, figures) into structured JSON format with automatic TOC generation. The extraction engine parses document.xml to identify heading styles, builds hierarchical section tree with paragraph indices, extracts table metadata (row/column counts, cell content), and catalogs figure captions. Supports chunked output with metadata for each chunk (chunk_index, strategy, section reference).
Automatically generates hierarchical table of contents from heading styles with paragraph index references, enabling direct navigation to specific paragraphs. Produces structured JSON with explicit section nesting and chunk metadata, suitable for RAG indexing and semantic search.
More structured than simple text extraction because it preserves document hierarchy and metadata; more accurate than regex-based heading detection because it uses HWPX style information directly.
keyword-search-with-context-window-retrieval
Medium confidenceSearches HWPX documents for keyword matches and returns results with configurable context windows (surrounding paragraphs). The search engine iterates through document paragraphs, performs case-insensitive substring matching, and returns match location (paragraph index, character offset) with surrounding context (previous/next N paragraphs). Supports regex patterns and exact phrase matching via parameter configuration.
Returns match location with paragraph-level context windows, enabling AI agents to understand surrounding content without loading entire document. Supports both substring and regex matching with configurable context depth.
Faster than full-document loading for targeted searches; more context-aware than simple find-and-replace because it returns surrounding paragraphs for semantic understanding.
search-and-replace-with-split-run-preservation
Medium confidencePerforms single or batch text replacement in HWPX documents with preservation of split-run formatting (text runs that span multiple formatting regions). The replacement engine locates target text, handles cases where text spans multiple XML runs (common in formatted documents), reconstructs runs to maintain formatting integrity, and saves changes back to the HWPX file. Batch mode supports multiple replacements in a single operation with atomic save.
Implements split-run aware replacement that reconstructs XML runs to preserve formatting when replacement text spans multiple formatting regions. Supports batch replacements with atomic save, enabling multi-step document transformations.
Preserves formatting metadata that naive string replacement would corrupt; more reliable than regex-based replacement because it understands HWPX XML structure.
paragraph-level-editing-with-insertion-and-deletion
Medium confidenceProvides granular paragraph-level editing operations: add new paragraphs (with optional style), insert paragraphs at specific indices, and delete paragraphs by index or range. The editing engine manipulates document.xml to insert/remove paragraph elements while maintaining document structure integrity, updates paragraph indices in cross-references, and optionally applies paragraph styles (heading, normal, list, etc.). Each operation is atomic and includes optional backup creation.
Provides index-based paragraph manipulation with style application, enabling precise document structure editing. Maintains document integrity by updating internal cross-references after insertions/deletions.
More precise than document-level editing because it operates at paragraph granularity; more flexible than template-based approaches because it supports arbitrary insertion/deletion at any index.
heading-insertion-with-style-application
Medium confidenceSpecialized paragraph insertion for adding heading elements with automatic style application (Heading 1, Heading 2, etc.). The operation inserts a new paragraph with specified heading level, applies corresponding style from document style sheet, and optionally adjusts surrounding paragraph styles for proper hierarchy. Supports insertion at specific indices or at document end.
Specialized heading insertion that automatically applies correct heading style based on level parameter, ensuring proper document hierarchy and TOC generation.
More convenient than generic paragraph insertion because it handles style application automatically; ensures proper heading hierarchy for TOC generation.
page-break-insertion-for-document-layout-control
Medium confidenceInserts page break elements into HWPX documents at specified paragraph indices, enabling control over document pagination and layout. The operation inserts a page break marker (special paragraph element) that forces subsequent content to a new page, useful for section separation or template-based document generation.
Provides explicit page break insertion at paragraph level, enabling precise pagination control in programmatically generated documents.
More reliable than relying on content size for pagination; enables predictable document layout in template-based generation.
memo-annotation-management-add-and-remove
Medium confidenceManages memo (comment/annotation) elements in HWPX documents with add and remove operations. The memo engine inserts memo markers at specified paragraph indices with configurable memo text, and removes existing memos by index. Memos are preserved in document metadata and visible in Hangeul application when document is opened.
Provides programmatic memo management that integrates with Hangeul application's native annotation system, enabling AI-driven document review workflows.
More integrated than external annotation systems because memos are stored in document metadata and visible in Hangeul; enables collaborative workflows between AI and human reviewers.
Capabilities are decomposed by AI analysis. Each maps to specific user intents and improves with match feedback.
Related Artifactssharing capabilities
Artifacts that share capabilities with 한글 mcp hwpx MCP Server , ranked by overlap. Discovered automatically through the match graph.
privateGPT
Ask questions to your documents without an internet connection, using the power of LLMs.
Haystack
Production NLP/LLM framework for search and RAG pipelines with component-based architecture.
llama-parse
Parse files into RAG-Optimized formats.
Hebbia
Revolutionize document analysis: AI collaboration, transparency, vast data...
Local GPT
Chat with documents without compromising privacy
rag-memory-epf-mcp
Project-local RAG memory MCP server — knowledge graph + multilingual vector + FTS5 in a single SQLite file. Per-project isolation, 30 MCP tools, codepoint-safe chunking (Korean/CJK/emoji).
Best For
- ✓Korean enterprise automation teams migrating from Windows-only COM-based Hangeul automation
- ✓Cross-platform CI/CD pipelines requiring HWPX processing on Linux/macOS without GUI dependencies
- ✓AI agents (Claude, Gemini) that need to read Korean documents as context before editing
- ✓Documentation teams converting legacy Hangeul documents to Markdown-based knowledge bases
- ✓LLM agents that need to chunk documents for RAG pipelines with section-aware boundaries
- ✓CI/CD workflows that require Markdown output for automated report generation
- ✓Document editing workflows that need safe backups before modifications
- ✓Batch document processing that generates variants from templates
Known Limitations
- ⚠Only supports HWPX (Open XML) format; legacy binary HWP files require conversion or separate tooling
- ⚠Text extraction respects document structure but may lose complex formatting metadata (font families, exact spacing)
- ⚠Character position tracking assumes UTF-8 encoding; mixed-encoding documents may have offset errors
- ⚠Maximum character return limited by HWPX_MCP_MAX_CHARS env var (default 10000) to prevent context overflow
- ⚠Complex formatting (multi-column layouts, embedded objects, custom shapes) is simplified to Markdown equivalents
- ⚠Images are referenced but not embedded in Markdown output; image extraction requires separate image-processing capability
Requirements
Input / Output
UnfragileRank
UnfragileRank is computed from adoption signals, documentation quality, ecosystem connectivity, match graph feedback, and freshness. No artifact can pay for a higher rank.
Repository Details
About
<p align="center"> <h1 align="center">📄 hwpx-mcp-server</h1> <p align="center"> <strong>한글(HWPX) 문서를 AI로 자동화하는 MCP 서버</strong> </p> <p align="center"> 한글 워드프로세서 없이 · 순수 파이썬 · 크로스 플랫폼 </p> <p align="center"> <a href="https://pypi.org/project/hwpx-mcp-server/"><img src="https://img.shields.io/pypi/v/hwpx-mcp-server?style=flat-square&color=blue" alt="PyPI"></a> <a href="https://pypi.org/project/hwpx-mcp-server/"><img src="https://img.shields.io/pypi/pyversions/hwpx-mcp-server?style=flat-square" alt="Python"></a> <a href="https://github.com/airmang/hwpx-mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/github/license/airmang/hwpx-mcp-server?style=flat-square" alt="License"></a> <a href="https://github.com/airmang/hwpx-mcp-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/airmang/hwpx-mcp-server/test.yml?style=flat-square&label=tests" alt="Tests"></a> </p> </p> --- **hwpx-mcp-server**는 [Model Context Protocol(MCP)](https://modelcontextprotocol.io) 표준을 따르는 서버로, [python-hwpx](https://github.com/airmang/python-hwpx) 기반에서 HWPX 문서의 열람 · 검색 · 편집 · 저장을 AI 클라이언트에서 직접 수행할 수 있게 합니다. > **Note** — 이 서버는 Open XML 기반 `.hwpx` 포맷을 지원합니다. 레거시 바이너리 `.hwp` 포맷은 직접 편집 대상이 아닙니다. <br> ## Why? 국내 공공기관·학교·기업에서는 한글 문서 기반 업무가 매우 많지만, 자동화는 오랫동안 OS/프로그램 의존성이 컸습니다. **hwpx-mcp-server**는 이 제약을 줄이는 데 초점을 맞춥니다. - ✅ **OS 무관** — Windows, macOS, Linux에서 동작 - ✅ **한글 워드프로세서 불필요** — 순수 파이썬 기반 처리 - ✅ **AI 네이티브** — Claude Desktop, VS Code, Gemini CLI 등 MCP 클라이언트와 직접 연결 - ✅ **Stateless 기본 설계** — 도구 호출마다 `filename`을 명시해 일관적으로 실행 <br> ## Use Cases - 실전 사용 사례 9개 보기: [`docs/use-cases.md`](docs/use-cases.md) - 종합 테스트 리포트: [`tests/hwpx_mcp_report_updated.md`](tests/hwpx_mcp_report_updated.md) <br> ## Quick Start ### 1. 설치 & 실행 [uv](https://docs.astral.sh/uv/getting-started/installation/) 기준: ```bash uvx hwpx-mcp-server ``` 또는 pip 설치: ```bash pip install hwpx-mcp-server hwpx-mcp-server ``` 요구사항: - `Python >= 3.10` - `python-hwpx >= 1.9` ### 2. MCP 클라이언트 설정 <details> <summary><b>Claude Desktop</b></summary> `claude_desktop_config.json`: ```json { "mcpServers": { "hwpx": { "command": "uvx", "args": ["hwpx-mcp-server"] } } } ``` </details> <details> <summary><b>Gemini CLI</b></summary> `~/.gemini/settings.json`: ```json { "mcpServers": { "hwpx": { "command": "uvx", "args": ["hwpx-mcp-server"] } } } ``` </details> <details> <summary><b>VS Code (Copilot Chat)</b></summary> `.vscode/mcp.json`: ```json { "servers": { "hwpx": { "command": "uvx", "args": ["hwpx-mcp-server"] } } } ``` </details> <details> <summary><b>Cursor / Windsurf</b></summary> 각 에디터 MCP 설정 파일에 동일한 블록을 추가: ```json { "mcpServers": { "hwpx": { "command": "uvx", "args": ["hwpx-mcp-server"] } } } ``` </details> ### 3. 전송 모드 선택 (Stdio + Streamable HTTP) 기본 `stdio` 사용은 기존과 동일합니다. ```bash hwpx-mcp-server ``` 동일한 MCP 도구 세트를 Streamable HTTP로 실행할 수 있습니다. ```bash hwpx-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000 ``` 환경 변수로도 동일하게 제어할 수 있습니다. - `HWPX_MCP_TRANSPORT` (`stdio` 또는 `streamable-http`) - `HWPX_MCP_HOST` (기본값: `127.0.0.1`) - `HWPX_MCP_PORT` (기본값: `8000`) > 참고: HTTP 인증은 현재 개발 편의 중심으로 단순하게 유지되어 있습니다. 프로덕션용 인증 훅은 서버 진입점에 TODO로 남겨두었습니다. <br> ## Features 기본 모드에서 30개 도구, 고급 모드(`HWPX_MCP_ADVANCED=1`)에서 추가 10개 도구가 활성화됩니다. ### 📖 읽기 & 탐색 | 도구 | 설명 | |---|---| | `get_document_info` | 문서 메타데이터/섹션/문단/표 개수 조회 | | `get_document_text` | 문서 전체 텍스트 추출 (`max_chars` 지원) | | `get_document_outline` | 제목/개요 구조 추출 | | `get_paragraph_text` | 특정 문단 텍스트 조회 | | `get_paragraphs_text` | 문단 범위 조회 | | `list_available_documents` | 폴더 내 `.hwpx` 파일 목록 조회 | ### 🧾 변환 & 추출 (입력 페이로드 기반) | 도구 | 설명 | |---|---| | `hwpx_to_markdown` | HWPX 입력을 Markdown으로 변환 | | `hwpx_to_html` | HWPX 입력을 HTML로 변환 | | `hwpx_extract_json` | HWPX 구조를 JSON으로 추출 | 공통 입력 규칙: - 입력 소스는 `hwpx_base64` 또는 `url` 중 정확히 하나만 허용 - `url`은 `https://...`만 허용 공통 옵션: - `output`: `full` 또는 `chunks` - `chunk_strategy`: `section` 또는 `paragraph` - `max_chars_per_chunk`: 청크당 최대 문자 수(기본값: `HWPX_MCP_MAX_CHARS_PER_CHUNK` 또는 `8000`) <details> <summary><b>변환/추출 응답 예시</b></summary> #### `hwpx_to_markdown` ```json { "markdown": "# Title\n\nParagraph...", "chunks": ["..."], "meta": { "source_type": "base64", "section_count": 2, "paragraph_count": 10, "table_count": 1, "figure_caption_count": 1 } } ``` #### `hwpx_to_html` ```json { "html": "<!doctype html><html>...</html>", "chunks": ["<section>...</section>"], "meta": { "source_type": "url", "image_policy": "omitted" } } ``` #### `hwpx_extract_json` ```json { "doc": { "title": "Title", "toc": [{ "level": 1, "text": "Title", "paragraph_index": 0 }], "sections": [{ "index": 0, "title": "Title", "paragraphs": [] }], "tables": [], "figures": [] }, "chunks": [{ "chunk_index": 0, "strategy": "section", "section": {} }], "meta": { "source_type": "base64" } } ``` </details> ### 🔎 검색 & 치환 | 도구 | 설명 | |---|---| | `find_text` | 키워드 검색 + 컨텍스트 반환 | | `search_and_replace` | 단일 치환 (split-run 보강) | | `batch_replace` | 다중 치환 일괄 실행 | ### ✏️ 편집 | 도구 | 설명 | |---|---| | `add_heading` | 제목(헤딩) 문단 추가 | | `add_paragraph` / `insert_paragraph` / `delete_paragraph` | 문단 추가/삽입/삭제 | | `add_page_break` | 페이지 나누기 추가 | | `add_memo` / `remove_memo` | 메모 추가/제거 | | `copy_document` | 문서 안전 복사 | ### 📊 표 | 도구 | 설명 | |---|---| | `add_table` / `get_table_text` | 표 생성/조회 | | `set_table_cell_text` | 셀 텍스트 수정 | | `merge_table_cells` / `split_table_cell` | 셀 병합/분할 | | `format_table` | 표 헤더 등 기본 서식 적용 | ### 🎨 스타일 | 도구 | 설명 | |---|---| | `format_text` | 텍스트 범위 서식 적용(굵기, 기울임, 밑줄, 색상 등) | | `create_custom_style` | 커스텀 스타일 생성 | | `list_styles` | 문서 스타일 목록 조회 | ### 🔬 고급 (옵션) `HWPX_MCP_ADVANCED=1`일 때 활성화: | 도구 | 설명 | |---|---| | `package_parts` | OPC 파트 목록 조회 | | `package_get_xml` / `package_get_text` | 파트 XML/텍스트 조회 | | `object_find_by_tag` / `object_find_by_attr` | XML 요소 검색 | | `plan_edit` / `preview_edit` / `apply_edit` | 편집 계획/미리보기/적용 | | `validate_structure` / `lint_text_conventions` | 구조 검증/텍스트 린트 | <br> ## Configuration | 변수 | 설명 | 기본값 | |---|---|---| | `HWPX_MCP_MAX_CHARS` | 텍스트 반환 도구 기본 최대 길이 | `10000` | | `HWPX_MCP_MAX_CHARS_PER_CHUNK` | 변환/추출 도구의 청크 분할 기본 길이 | `8000` | | `HWPX_MCP_AUTOBACKUP` | `1`이면 저장 전 `.bak` 백업 생성 | `1` | | `HWPX_MCP_ADVANCED` | `1`이면 고급 도구 활성화 | `0` | | `HWPX_MCP_TRANSPORT` | 서버 전송 모드 (`stdio`, `streamable-http`) | `stdio` | | `HWPX_MCP_HOST` | HTTP 바인딩 호스트 | `127.0.0.1` | | `HWPX_MCP_PORT` | HTTP 바인딩 포트 | `8000` | | `LOG_LEVEL` | 로그 레벨 | `INFO` | 환경 변수 포함 MCP 설정 예시: ```json { "mcpServers": { "hwpx": { "command": "uvx", "args": ["hwpx-mcp-server"], "env": { "HWPX_MCP_MAX_CHARS": "12000", "HWPX_MCP_MAX_CHARS_PER_CHUNK": "8000", "HWPX_MCP_AUTOBACKUP": "1", "HWPX_MCP_ADVANCED": "0", "HWPX_MCP_TRANSPORT": "stdio", "HWPX_MCP_HOST": "127.0.0.1", "HWPX_MCP_PORT": "8000", "LOG_LEVEL": "INFO" } } } } ``` <br> ## Advanced <details> <summary><b>📦 OPC 파트 조회</b></summary> 고급 모드에서 문서 내부 파트를 직접 조회할 수 있습니다. - `package_parts` - `package_get_xml` - `package_get_text` </details> <details> <summary><b>🧭 편집 파이프라인</b></summary> 고급 모드에서 `plan_edit → preview_edit → apply_edit` 흐름으로 변경 계획을 검토하고 적용할 수 있습니다. </details> <details> <summary><b>🧪 구조/규칙 검사</b></summary> 고급 모드에서 다음 검사 도구를 사용할 수 있습니다. - `validate_structure` - `lint_text_conventions` </details> <br> ## Testing ```bash # 테스트 의존성 설치 python -m pip install -e ".[test]" # 전체 테스트 python -m pytest -q ``` 로컬 기준(2026-02-22) 전체 테스트가 통과했습니다. - 실전 사용 사례: `docs/use-cases.md` - 종합 리포트: `tests/hwpx_mcp_report_updated.md` - 회귀 테스트: `tests/test_hwpx_report_regressions.py` <br> ## Architecture ```text hwpx-mcp-server ├── src/hwpx_mcp_server/ │ ├── server.py # Stateless MCP 진입점 │ ├── hwpx_ops.py # 고급/내부 연산 래퍼 │ ├── core/ # 문단/표/검색/서식 핵심 로직 │ ├── tools.py # 확장 도구 스키마/정의 │ └── schema/ # JSON 스키마 빌더/정리기 ├── tests/ # 단위 + E2E + 회귀 테스트 └── pyproject.toml ``` <br> ## Comparison | | hwpx-mcp-server | hwp(바이너리) COM 자동화 계열 | |---|---|---| | 대상 포맷 | `.hwpx` (Open XML) | `.hwp` (바이너리) 중심 | | OS | Windows · macOS · Linux | 대체로 Windows 중심 | | 한글 프로그램 의존 | 불필요 | 필요한 경우가 많음 | | 연동 방식 | MCP + 파이썬 라이브러리 | 데스크톱 앱 자동화 | <br> ## Contributing 기여를 환영합니다. 1. Fork 후 브랜치 생성 2. 변경 + 테스트 추가/수정 3. `pytest -q` 통과 확인 후 PR <br> ## License [MIT](LICENSE) © 고규현 (Kyuhyun Koh) <br> ## Author **고규현** — 광교고등학교 정보·컴퓨터 교사 - ✉️ [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com) - 🐙 [@airmang](https://github.com/airmang)
Categories
Alternatives to 한글 mcp hwpx MCP Server
Search the Supabase docs for up-to-date guidance and troubleshoot errors quickly. Manage organizations, projects, databases, and Edge Functions, including migrations, SQL, logs, advisors, keys, and type generation, in one flow. Create and manage development branches to iterate safely, confirm costs
Compare →AI-optimized web search and content extraction via Tavily MCP.
Compare →Scrape websites and extract structured data via Firecrawl MCP.
Compare →Are you the builder of 한글 mcp hwpx MCP Server ?
Claim this artifact to get a verified badge, access match analytics, see which intents users search for, and manage your listing.
Get the weekly brief
New tools, rising stars, and what's actually worth your time. No spam.
Data Sources
Looking for something else?
Search →