HWPX MCP Server

HWP/HWPX 문서를 AI로 읽고 편집할 수 있는 Model Context Protocol (MCP) 서버입니다.

특징

• 89개 도구: 문서의 모든 요소를 프로그래밍 방식으로 제어
• HWPX 완전 편집: 텍스트, 테이블, 이미지, 스타일, 머리글/꼬리글 등
• HWP 읽기 지원: 레거시 HWP 바이너리 포맷 읽기
• XML 무결성 보장: 모든 편집이 HWPML 규격에 맞게 XML에 저장
• 24개 E2E 테스트 통과: save-reload 검증 완료

설치

cd mcp-server
npm install
npm run build

설정

Claude Code (.vscode/mcp.json)

프로젝트 루트에 .vscode/mcp.json 파일 생성:

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

Claude Desktop (claude_desktop_config.json)

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

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

도구 목록 (89개)

문서 관리 (7개)

| 도구 | 설명 | |------|------| | get_tool_guide | 도구 가이드 조회 | | open_document | 문서 열기 (HWPX/HWP) | | create_document | 새 HWPX 문서 생성 | | save_document | 문서 저장 | | close_document | 문서 닫기 | | list_open_documents | 열린 문서 목록 | | get_document_metadata | 메타데이터 조회 | | set_document_metadata | 메타데이터 설정 |

문서 조회 (9개)

| 도구 | 설명 | |------|------| | get_document_text | 전체 텍스트 | | get_document_structure | 문서 구조 | | get_document_outline | 문서 개요 | | get_paragraphs | 문단 목록 | | get_paragraph | 특정 문단 상세 | | get_word_count | 단어 수 | | get_insert_context | 삽입 컨텍스트 | | find_insert_position_after_header | 헤더 다음 위치 찾기 | | find_insert_position_after_table | 테이블 다음 위치 찾기 |

텍스트 편집 (11개)

| 도구 | 설명 | |------|------| | insert_paragraph | 문단 삽입 | | update_paragraph_text | 문단 텍스트 수정 | | update_paragraph_text_preserve_styles | 스타일 유지 텍스트 수정 | | append_text_to_paragraph | 문단에 텍스트 추가 | | delete_paragraph | 문단 삭제 | | copy_paragraph | 문단 복사 | | move_paragraph | 문단 이동 | | search_text | 텍스트 검색 | | replace_text | 텍스트 치환 | | batch_replace | 일괄 치환 | | find_paragraph_by_text | 텍스트로 문단 찾기 |

서식 (스타일) (9개)

| 도구 | 설명 | |------|------| | get_text_style | 문자 스타일 조회 | | set_text_style | 문자 스타일 설정 (폰트, 크기, 볼드 등) | | get_paragraph_style | 문단 스타일 조회 | | set_paragraph_style | 문단 스타일 설정 (정렬, 줄간격 등) | | get_styles | 스타일 목록 | | get_char_shapes | 문자 모양 전체 | | get_para_shapes | 문단 모양 전체 | | apply_style | 스타일 적용 | | get_column_def | 단 설정 조회 | | set_column_def | 단 설정 |

내어쓰기 (8개)

| 도구 | 설명 | |------|------| | get_hanging_indent | 내어쓰기 조회 | | set_hanging_indent | 내어쓰기 설정 | | set_auto_hanging_indent | 자동 내어쓰기 | | remove_hanging_indent | 내어쓰기 제거 | | get_table_cell_hanging_indent | 셀 내어쓰기 조회 | | set_table_cell_hanging_indent | 셀 내어쓰기 설정 | | set_table_cell_auto_hanging_indent | 셀 자동 내어쓰기 | | remove_table_cell_hanging_indent | 셀 내어쓰기 제거 |

테이블 (23개)

| 도구 | 설명 | |------|------| | get_tables | 테이블 목록 | | get_table | 테이블 상세 | | get_table_cell | 셀 읽기 | | get_table_as_csv | CSV 내보내기 | | get_table_map | 테이블 맵 | | get_tables_summary | 테이블 요약 | | get_tables_by_section | 섹션별 테이블 | | find_table_by_header | 헤더로 테이블 찾기 | | find_empty_tables | 빈 테이블 찾기 | | get_element_index_for_table | 요소 인덱스 | | insert_table | 테이블 삽입 | | insert_nested_table | 중첩 테이블 | | delete_table | 테이블 삭제 | | update_table_cell | 셀 수정 | | replace_text_in_cell | 셀 텍스트 치환 | | set_cell_properties | 셀 속성 | | insert_table_row | 행 추가 | | delete_table_row | 행 삭제 | | insert_table_column | 열 추가 | | delete_table_column | 열 삭제 | | merge_cells | 셀 병합 | | split_cell | 셀 분할 | | copy_table | 테이블 복사 | | move_table | 테이블 이동 |

머리글/꼬리글/각주 (8개)

| 도구 | 설명 | |------|------| | get_header | 머리글 조회 | | set_header | 머리글 설정 | | get_footer | 꼬리글 조회 | | set_footer | 꼬리글 설정 | | get_footnotes | 각주 목록 | | insert_footnote | 각주 삽입 | | get_endnotes | 미주 목록 | | insert_endnote | 미주 삽입 |

이미지 (7개)

| 도구 | 설명 | |------|------| | get_images | 이미지 목록 | | insert_image | 이미지 삽입 | | update_image_size | 이미지 크기 변경 | | delete_image | 이미지 삭제 | | render_mermaid | Mermaid 다이어그램 삽입 | | insert_image_in_cell | 셀에 이미지 삽입 | | render_mermaid_in_cell | 셀에 Mermaid 삽입 |

북마크/하이퍼링크 (4개)

| 도구 | 설명 | |------|------| | get_bookmarks | 북마크 목록 | | insert_bookmark | 북마크 삽입 | | get_hyperlinks | 하이퍼링크 목록 | | insert_hyperlink | 하이퍼링크 삽입 |

수식/메모 (6개)

| 도구 | 설명 | |------|------| | get_equations | 수식 목록 | | insert_equation | 수식 삽입 | | get_memos | 메모 목록 | | insert_memo | 메모 삽입 | | delete_memo | 메모 삭제 |

도형 (3개)

| 도구 | 설명 | |------|------| | insert_line | 선 삽입 | | insert_rect | 사각형 삽입 | | insert_ellipse | 타원 삽입 |

섹션/페이지 (5개)

| 도구 | 설명 | |------|------| | get_sections | 섹션 목록 | | insert_section | 섹션 삽입 | | delete_section | 섹션 삭제 | | get_page_settings | 페이지 설정 조회 | | set_page_settings | 페이지 설정 |

실행 취소/다시 실행 (2개)

| 도구 | 설명 | |------|------| | undo | 실행 취소 | | redo | 다시 실행 |

내보내기 (2개)

| 도구 | 설명 | |------|------| | export_to_text | TXT 내보내기 | | export_to_html | HTML 내보내기 |

고급/디버깅 (8개)

| 도구 | 설명 | |------|------| | get_section_xml | 섹션 XML 조회 | | set_section_xml | 섹션 XML 설정 | | get_raw_section_xml | 원본 섹션 XML | | set_raw_section_xml | 원본 섹션 XML 설정 | | analyze_xml | XML 분석 | | repair_xml | XML 복구 | | chunk_document | 문서 청킹 | | invalidate_reading_cache | 읽기 캐시 무효화 |

검색/인덱싱 (5개)

| 도구 | 설명 | |------|------| | search_chunks | 청크 검색 | | get_chunk_context | 청크 컨텍스트 | | extract_toc | 목차 추출 | | build_position_index | 위치 인덱스 빌드 | | get_position_index | 위치 인덱스 조회 | | search_position_index | 위치 인덱스 검색 | | get_chunk_at_offset | 오프셋 청크 조회 |

사용 예시

예시 1: 테이블 편집

사용자: 사업계획서.hwpx를 열어서 3번째 테이블의 2행 1열을 수정해줘

AI 동작:
1. open_document("사업계획서.hwpx")
2. get_tables() → 테이블 목록 확인
3. get_table(section=0, index=2) → 구조 확인
4. update_table_cell(section=0, table=2, row=1, col=0, text="수정 내용")
5. save_document()

예시 2: 스타일 복사

사용자: 기존 양식의 스타일을 참고해서 새 문단을 추가해줘

AI 동작:
1. get_paragraph_style(sec=0, para=10) → {align: "Justify", lineSpacing: 145}
2. get_text_style(sec=0, para=10) → {fontName: "맑은 고딕", fontSize: 14}
3. insert_paragraph(sec=0, after=10, text="새 내용")
4. set_paragraph_style(sec=0, para=11, align="justify", line_spacing=145)
5. set_text_style(sec=0, para=11, font_name="맑은 고딕", font_size=14)
6. save_document()

예시 3: 자동 내어쓰기

사용자: 테이블 1행 1열에 "1. 항목\n2. 항목" 넣고 자동 내어쓰기 적용해줘

AI 동작:
1. update_table_cell(section=0, table=0, row=0, col=0, text="1. 항목\n2. 항목")
2. set_table_cell_auto_hanging_indent(section=0, table=0, row=0, col=0)
3. save_document()

테스트

cd mcp-server
npm test                    # vitest 단위 테스트
node test-mcp-e2e.mjs       # 16개 기본 E2E 테스트
node test-new-persistence-e2e.mjs  # 8개 persistence E2E 테스트

알려진 제한사항

• 각주/미주/북마크/하이퍼링크 삽입: 메모리에서만 동작, save 후 XML 미반영 (읽기는 정상)
• HWP 파일: 읽기 전용 (편집 불가)
• secPr 문단 스타일: 첫 번째 특수 문단에서 스타일 reload 제한

변경 이력

0.3.0 (2026-01-28)

• 대규모 XML persistence 수정: 8개 조작에 대한 save-reload 지원 추가
  • insertTableRow / deleteTableRow
  • insertTableColumn / deleteTableColumn
  • copyParagraph / moveParagraph (+ 같은 섹션 인덱스 버그 수정)
  • setHeader / setFooter
• depth-aware element indexing: 중첩 태그 내부 요소를 무시하는 안전한 파싱
• undo/redo 안전성: pending 배열 초기화로 메모리/XML 비동기화 방지
• replaceText 수정: XML entity 불일치 해결
• mergeCells 수정: indexOf 모호성 해결
• 테스트: 24개 E2E 테스트 (16 기본 + 8 persistence)

0.2.0

• 신규 기능: 테이블 셀 내 내어쓰기(Hanging Indent) 자동 적용
  • update_table_cell 시 마커(○, 1., 가., (1) 등) 감지하여 자동 내어쓰기
  • 멀티라인 텍스트의 각 줄에 독립적으로 내어쓰기 적용
  • set_table_cell_hanging_indent, get_table_cell_hanging_indent 도구 추가
• 버그 수정: 병렬 테이블 업데이트 시 XML 손상 문제 해결
  • 문서별 Lock 추가로 병렬 요청 직렬화 (race condition 방지)
  • findTableCellInXml() 중첩 테이블 처리 개선 (balanced bracket 매칭)
  • 여러 테이블 동시 수정 후 저장 시 "Broken tag structure" 오류 수정
• 버그 수정: 여러 테이블에 내어쓰기 적용 시 stale position 문제 해결
  • 테이블 인덱스 내림차순 처리로 위치 변경 영향 방지
  • 각 테이블 처리 시 위치 정보 재계산
• 테스트 강화: Red Team 스트레스 테스트 추가 (238개 테스트)
  • 50~200개 테이블 대량 수정 테스트
  • 중첩 테이블 + 내어쓰기 + 이미지 복합 테스트
  • 병렬 업데이트 시나리오 테스트

0.1.1

• 버그 수정: update_table_cell 후 save_document 시 빈 셀 변경사항이 저장되지 않던 문제 수정
  • Self-closing XML run 태그 (<hp:run ... />) 처리 지원 추가
  • ID 기반 테이블 매칭으로 정확한 XML 업데이트 구현
  • 원본 XML 구조를 최대한 보존하면서 텍스트만 수정

0.1.0

• 최초 릴리스

라이선스

MIT