사용 환경을 진단합니다. Python, pyhwpx, 한글 프로그램의 설치 여부를 확인하고 미설치 항목의 설치 방법을 안내합니다. 처음 사용하거나 에러 발생 시 이 도구를 먼저 호출하세요.

Python 의존성을 자동 설치합니다. (v0.7.4.6 신규, v0.7.4.7 확장) mcp-server/python/requirements.txt 기준 pip install. mode="all" (기본): pyhwpx+pywin32+PyMuPDF+pdfplumber+Pillow+opencv+numpy+paddlepaddle+paddleocr 전체 설치 (~700MB, 최대 20분). mode="core_only": paddlepaddle/paddleocr 제외 — native PDF clone 만 작동. force=true: sentinel 무시하고 재설치. v0.7.4.7 부터는 첫 HWP 도구 호출 시 자동으로 core_only 설치가 사전 실행되므로, 사용자가 이 도구를 명시 호출할 필요는 OCR 추가(mode:"all")나 재설치 시에만.

디렉토리 내 HWP/HWPX 파일 목록을 반환합니다. Python/한글 프로그램 없이도 사용 가능합니다. 문서 작업 전 파일 위치를 확인할 때 먼저 호출하세요.

지정된 경로의 HWP/HWPX 파일을 열어 편집 준비합니다. 이미 열린 문서가 있으면 자동으로 닫고 새 문서를 엽니다. 문서를 열면 hwp_analyze_document로 구조를 파악하세요.

현재 열린 HWP 문서를 닫습니다. 다른 문서를 열기 전이나 작업 완료 후 호출하세요.

현재 열린 문서를 지정된 경로와 형식으로 저장합니다. 편집 작업 후 반드시 호출하여 변경사항을 저장하세요.

현재 문서를 PDF로 내보냅니다. "PDF로 변환해줘" 요청에 사용하세요.

HWP/HWPX 문서의 전체 구조를 분석합니다. 페이지 수, 표(데이터 포함), 필드(양식), 본문 텍스트, 컨트롤 카탈로그(controls)를 반환합니다. 문서를 처음 다룰 때 반드시 이 도구를 먼저 호출하세요. v0.6.6+: HeadCtrl 순회로 표/그림/머리말/꼬리말/각주/누름틀 위치 자동 카탈로그.

현재 열린 HWP/HWPX 문서의 모든 컨트롤(표/그림/머리말/꼬리말/각주/미주/누름틀/하이퍼링크/책갈피/수식)을 HeadCtrl 순회로 나열합니다. 페이지 위치, 사용자 설명, 표 행/열 정보 포함. analyze_document보다 가벼움. CtrlID: tbl(표), gso(그림), head(머리말), foot(꼬리말), fn(각주), en(미주), %clk(누름틀), %hlk(하이퍼링크), bokm(책갈피), eqed(수식).

현재 열린 문서 또는 지정 파일의 본문 텍스트를 추출합니다. 문서 내용을 읽거나 검색할 때 사용하세요.

문서의 표 데이터를 조회합니다. 특정 표 인덱스를 지정하거나 전체 표를 반환합니다. 표 셀을 채우기 전에 구조를 확인할 때 사용하세요.

표의 셀을 Tab 순서로 순회하여 각 셀의 Tab 인덱스와 내용을 매핑합니다. 병합 셀이 있는 표에서 hwp_fill_table_cells의 tab 파라미터에 사용할 인덱스를 확인할 때 사용하세요.

현재 열린 문서의 경량 메타데이터(페이지 수, 파일 경로)를 빠르게 반환합니다. analyze_document보다 훨씬 빠릅니다. 문서가 열려 있는지, 몇 페이지인지만 빠르게 확인할 때 사용하세요.

문서에서 텍스트를 검색하고 발견된 위치와 횟수를 반환합니다. 치환 없이 검색만 합니다. 특정 텍스트가 문서에 있는지 확인하거나, 몇 번 등장하는지 파악할 때 사용하세요.

특정 표 셀의 글자 서식(글꼴, 크기, 자간, 장평, 굵기 등)과 단락 서식(정렬, 줄간격 등)을 조회합니다. 표 셀에 내용을 채우기 전에 해당 셀의 서식을 파악하여 동일한 서식으로 입력할 때 사용하세요.

표 전체의 서식 요약을 반환합니다. 샘플 셀들의 글꼴/크기/자간/장평/줄간격을 한번에 파악합니다. 표에 내용을 채우기 전에 서식 패턴을 파악할 때 사용하세요.

참고자료 파일(txt, csv, xlsx, json, md)의 내용을 추출합니다. 사업계획서 작성 시 참고 데이터를 가져올 때 사용하세요. HWP 파일은 hwp_analyze_document를 사용하세요.

문서의 필드(양식) 목록과 현재 값을 조회합니다. 필드를 채우기 전에 어떤 필드가 있는지 확인할 때 사용하세요.

문서 내용을 마크다운 형식으로 변환하여 반환합니다. 표는 마크다운 테이블로, 텍스트는 구조화됩니다. AI가 문서 내용을 이해하기 가장 좋은 형식입니다.

특정 페이지의 텍스트만 추출합니다. 전체 문서가 아닌 특정 페이지 내용만 필요할 때 사용하세요.

문서의 모든 이미지를 지정 디렉토리에 추출합니다. 문서 내 이미지를 파일로 가져올 때 사용하세요.

문서를 페이지 단위로 분할하여 별도 파일로 저장합니다. 긴 문서를 나눌 때 사용하세요.

문서에서 양식 필드(빈 괄호, 체크박스, 밑줄 등)를 자동 감지합니다. 양식을 채우기 전에 어떤 필드가 있는지 파악할 때 사용하세요.

문서 타입을 자동 감지해서 공무원 양식 표준 서식 프리셋을 추천합니다. (v0.7.5.4 신규) 타입: business_plan(사업계획서) / official_document(공문) / form(양식) / report(보고서) / general(일반). 결과의 recommended_preset 을 hwp_insert_body_after_heading 의 body_style 에 전달하면 표준 서식이 자동 적용됩니다. 사업계획서 / 공문 작업 전 가장 먼저 호출하세요.

양식 원본의 서식 프로파일을 스냅샷으로 캐시합니다. (v0.7.5.4 신규) body_default + heading_samples (레벨별) + table_cell_samples 를 JSON 으로 ~/.hwp_studio_state/snap_XXX.json 에 저장. 양식 첨부 후 한 번 호출하면 이후 insert_body_after_heading 호출 시 이 스냅샷 참조로 일관된 서식 적용 가능. 공무원 양식 작업의 첫 단계.

문서를 TEST_CHECKLIST Phase 19 의 5단계 검증 기준으로 평가합니다. (v0.7.5.4 신규) Stage 1 step_log (호출자 보장), 2 body_verified (chars ≥ expected×0.5), 3 file_size (22KB/28KB 하한), 4 text cross-check (snippet 90%+ 매칭), 5 layout PNG (opt-in). overall_pass 는 stage 1-4 모두 PASS 시 true. 신규 문서 작성 후 자동 검증에 사용.

양식 문서에서 서식 프로파일(글꼴/크기/자간/장평/줄간격/들여쓰기/여백)을 추출합니다. 양식 파일을 제공받았을 때 서식을 파악하여 동일하게 적용할 때 사용하세요.

현재 문서를 PNG 이미지로 변환하여 경로를 반환합니다. Claude가 Read 도구로 이미지를 읽어 표 구조, 셀 병합, 열 너비, 정렬 등을 시각적으로 검증합니다. 공문서 생성 후 결과물 확인에 사용하세요. PyMuPDF 필요(pip install PyMuPDF).

페이지 여백, 용지 크기, 방향을 설정합니다. 공문서 작성 전 페이지 설정에 사용하세요.

표 셀의 여백, 수직 정렬, 텍스트 방향, 보호 등 속성을 설정합니다.

글상자(텍스트박스)를 생성합니다. x/y로 위치, width/height로 크기를 지정합니다. 결재란 등 위치 지정이 필요한 요소에 사용하세요.

선을 그립니다. 두께, 색상, 스타일을 지정할 수 있습니다. hwp_insert_line보다 상세한 제어가 가능합니다.

머리글 또는 바닥글을 설정합니다. 기관명, 페이지번호 등을 삽입할 때 사용하세요. style로 서식(굵게/정렬/크기)을 지정할 수 있습니다.

현재 커서 위치에 문단 스타일을 적용합니다. "제목1", "본문", "개요1" 등 한글에 정의된 스타일을 사용합니다.

현재 섹션의 다단을 설정합니다. 2단/3단 레이아웃에 사용하세요.

표나 그림에 캡션(제목)을 삽입합니다.

현재 문서의 용지 설정을 읽습니다. 용지 크기, 방향, 여백(위/아래/좌/우/머리말/꼬리말), 제본 여백, 사용 가능 영역을 반환합니다.

표의 전체 너비, 셀 여백, 바깥 여백을 반환합니다. 양식 분석 시 표 구조를 정확히 재현하기 위해 사용합니다.

문서의 양식을 정밀 분석합니다. 용지 설정 + 본문 글자/문단 서식(19개 속성) + 표 치수(최대 5개)를 한번에 반환합니다. 양식 기반 문서 작성 전 반드시 호출하세요.

사용 가능한 한글 폰트 목록을 반환합니다. 카테고리별(serif/sans/display) 또는 공문서용(gov) 필터 가능. 40+종 한국어 폰트 포함.

사용 가능한 문서/표 프리셋 목록을 반환합니다. 공문서, 사업계획서, 제안서, 보고서 등 6종 문서 프리셋 + 4종 표 스타일.

문서 프리셋을 적용합니다. 용지 설정 + 기본 폰트/줄간격을 일괄 적용합니다. 프리셋: 공문서, 사업계획서, 제안서, 보고서, 계약서, 동의서.

문서의 필드(양식)에 값을 채웁니다. 반드시 먼저 hwp_get_fields로 필드 이름을 확인한 후 사용하세요. 필드가 없는 문서에는 hwp_fill_table_cells나 hwp_insert_text를 사용하세요.

문서의 표 셀에 값을 채웁니다. 반드시 먼저 hwp_get_tables로 표 구조를 확인하세요. 병합 셀이 있으면 label 파라미터로 라벨 텍스트 기반 매칭을 추천합니다. 예: {label: "계약금액", text: "50,000,000원"}. tab이나 row/col도 사용 가능합니다.

문서 전체에서 텍스트를 찾아 바꿉니다. use_regex=true로 정규식 패턴도 사용 가능합니다. case_sensitive=false로 대소문자 무시 검색 가능.

여러 건의 찾기/바꾸기를 일괄 실행합니다. use_regex=true로 정규식도 가능.

문서에서 텍스트를 찾은 후 그 뒤에 텍스트를 추가합니다. 색상 지정 가능. 기존 텍스트 서식을 보존하면서 새 텍스트를 추가할 때 사용하세요.

소제목 아래에 본문 단락을 삽입합니다. find_and_append 와 달리 (1) 목차(TOC) 항목 자동 skip, (2) 새 문단 분리 (BreakPara), (3) 본문 스타일 자동 리셋 (heading 스타일 상속 방지). 양식 채우기·사업계획서 작성 등에 권장.

현재 커서 위치에 텍스트를 삽입합니다. 필드가 없는 문서에 텍스트를 추가할 때 사용하세요. style로 글꼴/크기/굵기/색상 등 서식 지정 가능.

현재 커서 위치의 단락 서식을 변경합니다. left_margin=나머지줄 시작위치, indent=첫줄 들여쓰기. 첫줄 시작위치 = left_margin + indent. v0.6.7+: 문단 테두리(border_*) 4면 + first_line_indent alias + indent<0 자동 left_margin 보정.

문서에서 N번째로 나타나는 텍스트만 치환합니다. 같은 텍스트가 여러 곳에 있을 때 특정 위치만 바꿀 때 사용하세요. AllReplace는 전체를 바꾸지만 이 도구는 지정한 N번째만 바꿉니다.

현재 커서 위치에 이미지를 삽입합니다. 표 셀 안에서도 사용 가능. (v0.7.3) treat_as_char (글자처럼 취급) + embedded (본문에 박힘) 옵션 지원.

표에 행을 추가합니다. 표의 현재 마지막 행 아래에 새 행이 추가됩니다.

마크다운 텍스트를 한글 서식으로 변환하여 현재 커서 위치에 삽입합니다. # 제목, 굵게, - 목록 등을 지원합니다.

현재 커서 위치에 페이지 나누기를 삽입합니다.

표에서 현재 행을 삭제합니다.

표에 열을 추가합니다 (현재 열 오른쪽).

표에서 현재 열을 삭제합니다.

표의 셀을 병합합니다. start_row/col ~ end_row/col로 범위를 지정하면 해당 영역이 병합됩니다. 범위 미지정 시 현재 선택된 셀이 병합됩니다. 병합 순서는 하단→상단이 안전합니다.

2D 배열 데이터로 새 표를 생성합니다. col_widths/row_heights 로 mm 단위 정밀 레이아웃. (v0.7.3.1) cell 안 호출 시 자동으로 cell 폭 기반 col_widths 축소. row_heights 도 페이지 높이 자동 축소. treat_as_char 옵션으로 글자처럼 취급 on/off 제어 (cell 안 표는 한컴 자동 적용). (v0.7.6+) header_style=true 시 첫 행은 Bold + 가운데정렬 + 배경색 #E8E8E8 + 글자색 #333333 자동 적용 (header_bg_color/header_text_color 로 override).

제목 텍스트를 삽입합니다 (H1H9). 공문서 순번 체계의 대제목 등에 사용. numbering으로 자동 순번(텍스트 prefix)을 붙일 수 있습니다 (예: Ⅰ. 제목, 1. 제목, 가. 제목). v0.6.9+: auto_outline_level 옵션으로 ParaShape.OutlineLevel 자동 설정 → 한글 "개요 보기" + hwp_generate_toc 계층 인식 활성화. level 범위 16 → 1~9 확장.

현재 문서를 DOCX(Word) 형식으로 내보냅니다.

현재 문서를 HTML 형식으로 내보냅니다.

문서에 배경 이미지를 설정합니다. 워터마크로 활용 가능합니다.

표에서 현재 셀을 분할합니다. v0.6.8+: rows/cols 옵셔널 — 생략 시 기본 2×1 분할, 지정 시 HAction ParameterSet 경로로 정밀 분할.

현재 표 안에서 커서를 인접 셀로 이동합니다. (v0.6.8 신규) 표 바깥이면 에러. left/right/upper/lower 4방향. 사업계획서 표 정밀 편집 시 hwp_list_controls로 표 위치 확인 → 진입 → 이 도구로 셀 이동 → insert_row_at_cursor 등 조합.

현재 커서가 있는 셀 기준으로 행을 추가합니다. (v0.6.8 신규) 표 바깥이면 에러. above=위, below=아래, append=표 맨 끝. 기존 hwp_table_add_row는 table_index 지정 방식이고, 이 도구는 커서 위치 기반 — 사용자가 "여기에 한 줄 더" 요청 시 유용.

현재 이미 선택된 표 셀 블록을 병합합니다. (v0.6.8 신규) TableCellBlock + TableCellBlockExtend로 직접 블록을 만든 뒤 이 도구로 병합. 기존 hwp_table_merge_cells는 start_row/col + end_row/col 좌표 지정 방식이고, 이 도구는 "이미 선택된 상태" 전용.

지정된 표에 진입하여 첫 셀에 커서를 위치시킵니다. (v0.6.8.1 + v0.7.3.1 path-based) 평탄 인덱스 (number) 또는 nested 진입을 위한 path (number[]) 지원. path 형식: [outer_idx, row, col, inner_idx, row, col, inner_idx, ...] — 첫 원소는 outer table_index, 그 다음 (row, col, inner_idx) 3-원소 그룹 반복. 예: [0, 1, 1, 0] = 0번 표 → (1,1) 셀 → 그 셀 안의 0번 nested 표 (2단). 진입 후 hwp_navigate_cell/hwp_insert_text/hwp_table_create_from_data 등으로 셀 단위 작업 가능. 작업 완료 후 hwp_exit_table 호출.

현재 표에서 명시적으로 탈출합니다. (v0.6.8.1 신규) hwp_enter_table 후 셀 작업 완료 시 호출. 내부적으로 _exit_table_safely(MovePos(3) + BreakPara) 사용. 표 안에 없을 때 호출해도 안전 (no-op, was_in_cell=false 반환).

현재 커서 위치에 하이퍼링크를 삽입합니다.

현재 커서 위치에 각주를 삽입합니다. 학술 문서나 보고서에서 참조 주석을 달 때 사용하세요.

현재 커서 위치에 미주를 삽입합니다.

현재 커서 위치에 쪽 번호를 삽입합니다. format으로 형식을 지정할 수 있습니다 (예: - 1 -, (1)).

현재 커서 위치에 오늘 날짜를 자동 삽입합니다.

표에서 합계를 자동 계산합니다. 현재 셀 위치에서 한글의 자동 합계 기능을 실행합니다.

표에서 평균을 자동 계산합니다. 현재 셀 위치에서 한글의 자동 평균 기능을 실행합니다.

표 데이터를 CSV 파일로 내보냅니다.

현재 위치에 섹션 나누기를 삽입합니다.

현재 위치에 다단 나누기를 삽입합니다.

현재 위치에 선(줄)을 삽입합니다.

표의 행과 열을 교환합니다.

자동 번호매기기를 삽입합니다.

메모 필드를 삽입합니다.

표 셀 너비를 균등하게 분배합니다.

현재 커서 위치의 단락을 들여쓰기합니다 (Shift+Tab 효과). 공문서 순번 체계에서 하위 항목 들여쓰기에 사용.

현재 커서 위치의 단락 들여쓰기를 줄입니다 (내어쓰기).

양식의 작성요령 박스 내용을 구조화 추출합니다 (v0.7.7 신규). 삭제 전에 호출하여 각 섹션별 요구사항(페이지 제한, 필수 기재, 형식 요구)을 보존. 결과를 AI 콘텐츠 생성 컨텍스트로 활용.

양식의 작성요령/가이드 텍스트를 자동 삭제합니다. v0.7.5.4 업그레이드: scope="text"(기존 텍스트 리터럴), "table"(작성요령 박스 표 전체 삭제), "both"(둘 다). 공공기관 양식 작성 후 제출 전에 사용. 기본 scope="both" 권장. v0.7.7: extract_first=true 로 삭제 전 작성요령 내용 자동 추출.

문서의 체크박스를 전환합니다 (□→■, ☐→☑ 등). 양식에서 특정 항목을 체크할 때 사용.

표 셀의 배경색을 설정합니다. 간트차트 음영, 헤더행 강조, 데이터 시각화 등에 사용.

표의 테두리 스타일을 설정합니다. 표 전체 또는 특정 셀의 테두리를 변경할 수 있습니다.

[개발용] pyhwpx COM 객체의 실제 속성 목록을 덤프합니다. HCharShape/HParaShape 등의 정확한 속성명을 확인할 때 사용.

하나의 템플릿으로 여러 건의 문서를 생성합니다. 각 데이터마다 템플릿을 별도 파일로 복사 후 채우기/치환하므로 AllReplace 범위 문제가 없습니다. 같은 양식에 여러 사람/기업 데이터를 채울 때 사용하세요.

표 셀 채우기 + 서식 자동 감지/보존. hwp_fill_table_cells와 달리 각 셀의 글꼴/크기/자간/장평을 자동 감지하고 유지합니다. 공공기관 문서처럼 서식이 중요한 경우 이 도구를 사용하세요. 적용된 서식 정보도 반환합니다.

참고자료(Excel/CSV)의 헤더와 표의 라벨을 자동 매칭하여 채울 데이터를 생성합니다. 매핑 결과를 확인한 후 hwp_fill_table_cells로 실제 채우기를 진행하세요. hwp_read_reference로 데이터를 읽은 뒤 이 도구로 매핑하면 편리합니다.

CSV 또는 Excel 파일을 읽어서 표로 자동 생성합니다. 현재 커서 위치에 헤더+데이터가 포함된 표가 삽입됩니다.

현재 열린 문서에 다른 HWP 문서의 내용을 합칩니다. 여러 문서를 하나로 합칠 때 사용하세요.

문서를 분석하고 빈 필드/셀을 강조하며 작성 완성도(%)를 계산합니다. 문서 상태를 한눈에 파악하고 다음 작업을 결정할 때 사용하세요.

문서 텍스트에서 개인정보(주민번호, 전화번호, 이메일, 계좌번호 등)를 자동 감지합니다. 공공기관 문서 제출 전 개인정보 포함 여부를 확인할 때 사용하세요.