HWP Metadata MCP Server

한글(HWP/HWPX) 파일의 메타데이터를 추출하는 MCP(Model Context Protocol) 서버입니다.

기능

• HWP 5.0 지원: OLE 기반 바이너리 HWP 파일
• HWPX 지원: XML 기반 오픈 포맷 HWPX 파일
• 자동 감지: 파일 형식을 자동으로 감지하여 처리
• 크로스 플랫폼: Windows, Linux, macOS 지원
• HWP 설치 불필요: 순수 Python 라이브러리로 구현

추출 가능한 메타데이터

• 문서 정보: 제목, 작성자, 키워드, 주제, 설명
• 시간 정보: 생성일, 수정일, 마지막 인쇄일
• 문서 통계: 페이지 수, 단어 수, 문자 수, 문단 수
• 보안 정보: 암호화 여부, 읽기 전용 여부
• 기술 정보: HWP 버전, 사용된 글꼴 목록
• 애플리케이션 정보: 생성 프로그램 및 버전

설치

# pip 사용
pip install hwp-metadata-mcp

# uv 사용 (권장)
uv add hwp-metadata-mcp

# 개발 버전 설치
git clone https://github.com/heonseung4-del/hwp-metadata-mcp
cd hwp-metadata-mcp
uv pip install -e .

사용법

Claude Desktop에서 사용

claude_desktop_config.json 파일에 다음을 추가하세요:

Windows: %APPDATA%/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hwp-metadata": {
      "command": "uvx",
      "args": ["hwp-metadata-mcp"]
    }
  }
}

또는 로컬 설치된 경우:

{
  "mcpServers": {
    "hwp-metadata": {
      "command": "python",
      "args": ["-m", "hwp_metadata_mcp.server"]
    }
  }
}

Python에서 직접 사용

from hwp_metadata_mcp.hwp_parser import HwpParser
from hwp_metadata_mcp.hwpx_parser import HwpxParser
from hwp_metadata_mcp.hwp_parser import detect_file_type

# 자동 감지
file_type = detect_file_type("document.hwp")
if file_type == "HWP":
    metadata = HwpParser.parse("document.hwp")
elif file_type == "HWPX":
    metadata = HwpxParser.parse("document.hwpx")

# 메타데이터 접근
print(f"제목: {metadata.title}")
print(f"작성자: {metadata.author}")
print(f"페이지 수: {metadata.page_count}")
print(f"생성일: {metadata.created_date}")

MCP Tools

서버는 다음 3개의 tool을 제공합니다:

1. extract_metadata (권장)

파일 형식을 자동으로 감지하여 메타데이터 추출

# Claude Desktop에서:
# "이 HWP 파일의 메타데이터를 알려줘: /path/to/file.hwp"

2. extract_hwp_metadata

HWP 5.0 파일 전용

3. extract_hwpx_metadata

HWPX 파일 전용

MCP Resources

URI를 통해 메타데이터 조회:

hwp://metadata//path/to/document.hwp
hwp://metadata//path/to/document.hwpx

개발

요구사항

• Python 3.10 이상
• mcp >= 1.0.0
• pydantic >= 2.0.0
• olefile >= 0.46

로컬 테스트

# MCP Inspector로 테스트
uv run mcp dev src/hwp_metadata_mcp/server.py

# 직접 실행
uv run python -m hwp_metadata_mcp.server

테스트 실행

# 테스트 패키지 설치
uv add --dev pytest pytest-asyncio

# 테스트 실행
pytest tests/

지원 환경

• OS: Windows, Linux, macOS
• Python: 3.10, 3.11, 3.12
• HWP: 5.0 이상
• HWPX: 모든 버전

제한사항

• 암호화된 HWP 파일: 암호화 여부는 확인 가능하지만, 암호로 보호된 파일의 상세 메타데이터는 추출할 수 없습니다
• 문서 내용: 메타데이터만 추출하며, 본문 텍스트는 추출하지 않습니다
• 편집 기능 없음: 읽기 전용입니다. 파일 편집은 지원하지 않습니다

라이선스

BSD-3-Clause License

기여

이슈 및 Pull Request를 환영합니다!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

관련 프로젝트

• pyhwp - HWP 파일 파서 및 변환기
• olefile - OLE 파일 파서
• MCP - Model Context Protocol

문의

이슈를 통해 문의해주세요: GitHub Issues