a

airmang-hwpx-mcp

@smithery/airmang-hwpx-mcp
Hosted
0 Stars 6 次浏览 smithery 更新于 2026-08-23

鞛愲彊頇旐晿鞐� HWPX 氍胳劀鞚� 搿滊敥, 韮愳儔, 韼胳, 瓴�歃濎潉 頃� 氩堨棎 觳橂Μ頃╇媹雼�. 氍鸽嫧路響溌缝＜靹� 於旉皜, 韰嶌姢韸� 鞚缄磩 旃橅櫂, 毹鸽Μ毵惵逢棘毽 靹れ爼 霌� 氚橂车 鞛戩梾鞚� 鞁犾啀頌� 靾橅枆頃╇媹雼�. 旮扳��

文件系统
该服务暂未提供标准配置，请参考 README 手动接入

可用工具 （5 个）

该服务在 MCP 协议中暴露的工具，AI 可按需调用

tavily_search 14 个参数 需填 1 项

Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.

必填参数：query

tavily_extract 6 个参数 需填 1 项

Extract content from URLs. Returns raw page content in markdown or text format.

必填参数：urls

tavily_crawl 11 个参数 需填 1 项

Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.

必填参数：url

tavily_map 8 个参数 需填 1 项

Map a website's structure. Returns a list of URLs found starting from the base URL.

必填参数：url

tavily_research 2 个参数 需填 1 项

Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings.

必填参数：input

服务介绍

hwpx-mcp-server는 Model Context Protocol(MCP) 표준을 따르는 서버로, python-hwpx 기반에서 HWPX 문서의 열람 · 검색 · 편집 · 저장을 AI 클라이언트에서 직접 수행할 수 있게 합니다.

Note — 이 서버는 Open XML 기반 .hwpx 포맷을 지원합니다. 레거시 바이너리 .hwp 포맷은 직접 편집 대상이 아닙니다.

# Why?

국내 공공기관·학교·기업에서는 한글 문서 기반 업무가 매우 많지만, 자동화는 오랫동안 OS/프로그램 의존성이 컸습니다.

hwpx-mcp-server는 이 제약을 줄이는 데 초점을 맞춥니다.

  • ✅ OS 무관 — Windows, macOS, Linux에서 동작
  • ✅ 한글 워드프로세서 불필요 — 순수 파이썬 기반 처리
  • ✅ AI 네이티브 — Claude Desktop, VS Code, Gemini CLI 등 MCP 클라이언트와 직접 연결
  • ✅ Stateless 기본 설계 — 도구 호출마다 filename을 명시해 일관적으로 실행

# Use Cases

# Quick Start

# # 1. 설치 & 실행

uv 기준:

uvx hwpx-mcp-server

또는 pip 설치:

pip install hwpx-mcp-server
hwpx-mcp-server

요구사항:

  • Python >= 3.10
  • python-hwpx >= 1.9

# # 2. MCP 클라이언트 설정

claude_desktop_config.json:

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

~/.gemini/settings.json:

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

.vscode/mcp.json:

{
  "servers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

각 에디터 MCP 설정 파일에 동일한 블록을 추가:

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

# # 3. 전송 모드 선택 (Stdio + Streamable HTTP)

기본 stdio 사용은 기존과 동일합니다.

hwpx-mcp-server

동일한 MCP 도구 세트를 Streamable HTTP로 실행할 수 있습니다.

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로 남겨두었습니다.

# 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)

# # # hwpx_to_markdown

{
  "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

{
  "html": "<!doctype html><html>...</html>",
  "chunks": ["<section>...</section>"],
  "meta": {
    "source_type": "url",
    "image_policy": "omitted"
  }
}

# # # hwpx_extract_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"
  }
}

# # 🔎 검색 & 치환

| 도구 | 설명 |
|- --|- --|
| 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 | 구조 검증/텍스트 린트 |

# 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 설정 예시:

{
  "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"
      }
    }
  }
}

# Advanced

고급 모드에서 문서 내부 파트를 직접 조회할 수 있습니다.

  • package_parts
  • package_get_xml
  • package_get_text

고급 모드에서 plan_edit → preview_edit → apply_edit 흐름으로 변경 계획을 검토하고 적용할 수 있습니다.

고급 모드에서 다음 검사 도구를 사용할 수 있습니다.

  • validate_structure
  • lint_text_conventions

# Testing

#  테스트 의존성 설치
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

# Architecture

hwpx-mcp-server
├── src/hwpx_mcp_server/
│   ├── server.py            #  Stateless MCP 진입점
│   ├── hwpx_ops.py          #  고급/내부 연산 래퍼
│   ├── core/                #  문단/표/검색/서식 핵심 로직
│   ├── tools.py             #  확장 도구 스키마/정의
│   └── schema/              #  JSON 스키마 빌더/정리기
├── tests/                   #  단위 + E2E + 회귀 테스트
└── pyproject.toml

# Comparison

| | hwpx-mcp-server | hwp(바이너리) COM 자동화 계열 |
|- --|- --|- --|
| 대상 포맷 | .hwpx (Open XML) | .hwp (바이너리) 중심 |
| OS | Windows · macOS · Linux | 대체로 Windows 중심 |
| 한글 프로그램 의존 | 불필요 | 필요한 경우가 많음 |
| 연동 방식 | MCP + 파이썬 라이브러리 | 데스크톱 앱 자동화 |

# Contributing

기여를 환영합니다.

  1. Fork 후 브랜치 생성
  2. 변경 + 테스트 추가/수정
  3. pytest -q 통과 확인 후 PR

# License

MIT © 고규현 (Kyuhyun Koh)

# Author

고규현 — 광교고등학교 정보·컴퓨터 교사

查看源码 项目主页

相关 MCP 服务

文件系统
@modelcontextprotocol/filesystem
实现用于文件系统操作的模型上下文协议（MCP）的 Node.js 服务器。
E
Excel文件服务
@negokaz/excel-mcp-server
一个模型上下文协议服务器，使人工智能助手能够读取和写入Microsoft Excel文件，支持xlsx、xlsm、xltx和xltm等格式。
A
AI Word文档助手
@GongRzhe/Office-Word-MCP-Server
一个模型上下文协议服务器，它使人工智能助手能够通过标准化的工具和资源创建、读取、编辑和格式化Microsoft Word文档。
D
DOCX/PDF文档生成服务-MCP（MCP&Agent挑战赛）
KUN03036/LLM_output_with_docxpdf_MCP_Agent_Challenge
暂无简介