claude-code-hwp-mcp 0.2.0 → 0.2.2

package/README.md

@@ -1,397 +1,467 @@
 # claude-code-hwp-mcp
 
-Claude Code에서 한글(HWP) 문서를 직접 제어하는 MCP 서버입니다.
-pyhwpx COM API를 통해 문서 열기, 편집, 분석, 저장, 변환까지 **85개+ 도구**를 제공합니다.
+Claude Code와 Claude Desktop에서 한글(HWP) 문서를 AI로 자동 편집하는 MCP 서버입니다.
 
-> **Windows 전용** | 한글(HWP) 2014 이상 | Python 3.8+ | Claude Code / Claude Desktop 지원
+85개 이상의 도구로 문서 열기, 표 채우기, 텍스트 편집, 서식 설정, PDF 변환까지 모두 자동화할 수 있습니다.
+
+> Windows 전용 | 한글 2014 이상 | Python 3.8+ | Claude Code + Claude Desktop 지원
 
 ---
 
-## 목차
+## 설치 가이드 (처음 설정하는 분)
 
-- [설치 방법](#설치-방법)
-- [Claude Code 설정](#claude-code-설정)
-- [Claude Desktop 설정](#claude-desktop-설정)
-- [사용 방법](#사용-방법)
-- [기능 목록 (85개+)](#기능-목록-85개)
-- [아키텍처](#아키텍처)
-- [문제 해결](#문제-해결)
+아래 순서대로 따라하세요. 5분이면 완료됩니다.
 
----
+### Step 1. Python 설치
 
-## 설치 방법
+**반드시 python.org 공식 버전을 설치하세요.**
 
-### 1단계: 사전 요구사항 설치
+1. https://www.python.org/downloads/ 에 접속
+2. "Download Python 3.x.x" 버튼 클릭
+3. 설치 화면에서 **"Add Python to PATH" 체크박스를 반드시 체크**
+4. "Install Now" 클릭
 
-| 요구사항 | 설치 방법 |
-|----------|-----------|
-| **Windows 10/11** | macOS/Linux는 지원하지 않습니다 (COM API 기반) |
-| **한글(HWP) 프로그램** | 한컴오피스 한글 2014 이상. 설치 후 한번 실행하여 초기 설정 완료 |
-| **Python 3.8+** | [python.org](https://www.python.org/downloads/)에서 설치. **설치 시 "Add Python to PATH" 반드시 체크** |
-| **Node.js 18+** | [nodejs.org](https://nodejs.org/)에서 LTS 버전 설치 |
+> **Microsoft Store 버전 Python은 사용하지 마세요.** Store 버전은 패키지가 격리된 경로에 설치되어 pyhwpx를 인식하지 못합니다. 이미 Store 버전이 설치되어 있다면 [Microsoft Store Python 문제 해결](#microsoft-store-python-문제) 섹션을 참고하세요.
 
-### 2단계: Python 패키지 설치
+설치 확인 (명령 프롬프트에서):
 
 ```bash
-pip install pyhwpx pywin32
+python --version
 ```
 
-### 3단계: MCP 서버 설치
+`Python 3.x.x`가 출력되면 성공입니다.
+
+### Step 2. Python 패키지 설치
+
+명령 프롬프트(cmd)를 열고 아래를 실행하세요:
 
-**방법 A: npm 글로벌 설치 (권장)**
 ```bash
-npm install -g claude-code-hwp-mcp
+pip install pyhwpx pywin32
 ```
 
-**방법 B: GitHub에서 직접 클론**
+설치 확인:
+
 ```bash
-git clone https://github.com/gmlcjf0326/claude-code-hwp-mcp.git
-cd claude-code-hwp-mcp
-npm install
-npm run build
+pip show pyhwpx
 ```
 
-### 4단계: 환경 확인
+### Step 3. Node.js 설치
 
-설치 후 `hwp_check_setup` 도구를 호출하면 환경을 자동 진단합니다:
-```
-✅ Python 3.11.5
-✅ pyhwpx installed
-✅ 한글(HWP) 프로그램
-→ 모든 요구사항이 충족되었습니다.
+1. https://nodejs.org/ 에 접속
+2. LTS 버전 다운로드 후 설치
+
+### Step 4. MCP 서버 설치
+
+명령 프롬프트에서:
+
+```bash
+npm install -g claude-code-hwp-mcp
 ```
 
+### Step 5. Claude에 MCP 서버 연결
+
+사용하는 Claude 앱에 따라 아래 설정을 진행하세요:
+
+- **Claude Code** 사용자 → [Claude Code 설정](#claude-code-설정) 섹션으로
+- **Claude Desktop** 사용자 → [Claude Desktop 설정](#claude-desktop-설정) 섹션으로
+
 ---
 
 ## Claude Code 설정
 
-`~/.claude/settings.json`에 MCP 서버를 등록합니다:
+### 설정 파일 열기
+
+Claude Code 터미널에서 설정 파일을 엽니다. 파일 위치:
+
+- Windows: `C:\Users\사용자이름\.claude\settings.json`
+- 또는 `~/.claude/settings.json`
+
+### 설정 추가
+
+`settings.json` 파일에 아래 내용을 추가하세요:
 
-**npm 글로벌 설치한 경우:**
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
-      "command": "hwp-mcp",
-      "args": []
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp"
     }
   }
 }
 ```
 
-**GitHub 클론한 경우:**
+이미 다른 MCP 서버가 등록되어 있다면 `mcpServers` 안에 추가합니다:
+
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
-      "command": "node",
-      "args": ["C:/경로/claude-code-hwp-mcp/dist/index.js"]
+    "기존-서버": {
+      "command": "기존-명령"
+    },
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp"
     }
   }
 }
 ```
 
-**토큰 절약 모드 (도구 15개만 로드):**
+### GitHub 클론 방식으로 설치한 경우
+
+npm 글로벌 설치 대신 GitHub에서 클론한 경우:
+
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
-      "command": "hwp-mcp",
-      "args": ["--toolset=minimal"]
+    "claude-code-hwp-mcp": {
+      "command": "node",
+      "args": ["C:\\claude-code-hwp-mcp\\dist\\index.js"]
     }
   }
 }
 ```
 
+`args`의 경로를 실제 클론한 위치로 변경하세요.
+
 ---
 
 ## Claude Desktop 설정
 
-`claude_desktop_config.json`에 추가:
+### Step 1. 설정 파일 찾기
+
+Windows 탐색기에서 주소창에 아래를 입력하고 Enter:
+
+```
+%APPDATA%\Claude
+```
+
+`Claude` 폴더가 열립니다.
+
+### Step 2. 설정 파일 만들기 또는 열기
+
+해당 폴더에 `claude_desktop_config.json` 파일이 있으면 메모장으로 엽니다.
+
+파일이 없으면 새로 만드세요:
+1. 폴더에서 마우스 우클릭 > 새로 만들기 > 텍스트 문서
+2. 파일 이름을 `claude_desktop_config.json`으로 변경 (확장자 `.txt`가 아닌 `.json`)
+
+### Step 3. 설정 내용 입력
+
+파일에 아래 내용을 그대로 붙여넣으세요:
+
+```json
+{
+  "mcpServers": {
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp"
+    }
+  }
+}
+```
+
+### Step 4. (선택) Python 경로 직접 지정
+
+Python이 여러 개 설치되어 있거나 Microsoft Store Python 문제가 있을 경우, Python 경로를 명시적으로 지정할 수 있습니다:
 
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
+    "claude-code-hwp-mcp": {
       "command": "hwp-mcp",
-      "args": []
+      "env": {
+        "PYTHON_PATH": "C:\\Users\\사용자이름\\AppData\\Local\\Programs\\Python\\Python313\\python.exe"
+      }
     }
   }
 }
 ```
 
-설정 파일 위치:
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+본인의 Python 경로를 확인하려면 명령 프롬프트에서:
+
+```bash
+python -c "import sys; print(sys.executable)"
+```
+
+출력된 경로를 `PYTHON_PATH` 값으로 사용하세요.
+
+### Step 5. Claude Desktop 재시작
+
+설정 파일을 저장한 후 **Claude Desktop을 완전히 종료했다가 다시 실행**하세요. (트레이에서도 완전 종료)
+
+### Step 6. 연결 확인
+
+Claude Desktop에서 아래와 같이 입력하세요:
+
+```
+hwp_check_setup 실행해줘
+```
+
+모든 항목에 체크 표시가 나오면 성공입니다.
 
 ---
 
-## 사용 방법
+## 사용 전 반드시 확인
+
+**한글(HWP) 프로그램이 실행 중이어야 합니다.**
+
+MCP 서버는 한글 프로그램의 COM API를 통해 문서를 제어합니다. 한글이 열려 있지 않으면 문서 관련 도구가 동작하지 않습니다.
 
-### 기본 흐름
+사용 순서:
+1. 한글(HWP) 프로그램을 실행합니다
+2. 빈 문서가 열린 상태로 둡니다
+3. Claude Code 또는 Claude Desktop에서 작업을 시작합니다
 
-Claude Code에서 자연어로 요청하면 됩니다:
+---
+
+## 사용 예시
+
+Claude에게 자연어로 요청하면 됩니다:
 
 ```
 "C:/문서/사업계획서.hwp 파일을 열어서 분석해줘"
 "표의 계약금액 칸에 50,000,000원을 채워줘"
 "문서를 PDF로 변환해줘"
+"작성요령 텍스트 삭제해줘"
+"참고자료.xlsx를 읽어서 양식.hwp의 표를 자동으로 채워줘"
+"직원_명단.xlsx의 각 행으로 위촉장.hwp를 개별 생성해줘"
 ```
 
-### 예시: 공문서 양식 채우기
+---
+
+## 문제 해결
+
+### Microsoft Store Python 문제
+
+**증상**: hwp_check_setup에서 "pyhwpx 미설치" 또는 "한글 미설치"로 표시되지만 실제로는 설치되어 있음
 
+**진단**: 명령 프롬프트에서 아래를 실행하세요:
+
+```bash
+python -c "import sys; print(sys.executable)"
 ```
-1. "C:/양식/과업지시서.hwp 열어줘"
-2. "문서 구조를 분석해줘"
-3. "표에서 '사업명' 칸에 'AI 문서 자동화 프로젝트'를 채워줘"
-4. "작성요령 텍스트 삭제해줘"
-5. "저장하고 PDF로도 내보내줘"
+
+출력 경로에 `WindowsApps`가 포함되어 있으면 Microsoft Store 버전입니다:
+
 ```
+C:\Users\사용자\AppData\Local\Microsoft\WindowsApps\python.exe  (Store 버전)
+```
+
+**해결 방법 A (권장): python.org 버전으로 재설치**
+
+1. Windows 설정 > 앱 > "Python"을 찾아서 제거
+2. https://www.python.org/downloads/ 에서 다시 설치
+3. 설치 시 "Add Python to PATH" 반드시 체크
+4. `pip install pyhwpx pywin32` 다시 실행
 
-### 예시: 엑셀 데이터로 자동 채우기
+**해결 방법 B: Claude 설정에서 Python 경로 지정**
 
+Store Python을 유지한 채, MCP 설정에서 직접 경로를 지정합니다:
+
+```json
+{
+  "mcpServers": {
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp",
+      "env": {
+        "PYTHON_PATH": "C:\\Users\\사용자\\AppData\\Local\\Programs\\Python\\Python313\\python.exe"
+      }
+    }
+  }
+}
 ```
-"참고자료.xlsx를 읽어서 양식.hwp의 표를 자동으로 채워줘"
+
+### Python을 찾을 수 없습니다
+
+python.org에서 Python 3.8+을 설치하세요. 설치 시 "Add Python to PATH" 체크 필수입니다. 설치 후 명령 프롬프트를 새로 열어야 합니다.
+
+### pyhwpx 모듈을 찾을 수 없습니다
+
+```bash
+pip install pyhwpx pywin32
 ```
-→ `hwp_auto_fill_from_reference` 도구가 엑셀 헤더를 표 라벨과 자동 매칭합니다.
 
-### 예시: 다건 문서 생성
+### COM class not registered
+
+한컴오피스 한글을 설치하세요. 설치 후 한글을 한번 실행하여 초기 설정을 완료하세요.
+
+### RPC 서버를 사용할 수 없습니다
+
+한글 프로그램을 닫고 다시 시도하세요. 작업 관리자(Ctrl+Shift+Esc)에서 Hwp.exe 프로세스가 남아있으면 종료 후 재시도하세요.
+
+### 환경 자동 진단
+
+Claude에게 요청하세요:
 
 ```
-"직원_명단.xlsx의 각 행으로 위촉장.hwp를 개별 생성해줘"
+"hwp_check_setup 실행해줘"
 ```
-→ `hwp_generate_multi_documents`가 행마다 별도 HWP 파일을 생성합니다.
+
+Python 경로, pyhwpx 설치 여부, 한글 프로그램 설치 및 실행 상태를 자동으로 확인합니다.
 
 ---
 
 ## 기능 목록 (85개+)
 
-### 환경/진단 (1개)
+### 환경/문서 관리 (6개)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_check_setup` | Python/pyhwpx/한글 설치 상태 진단 및 안내 |
-
-### 문서 관리 (5개)
-
-| 도구 | 설명 |
-|------|------|
-| `hwp_list_files` | 디렉토리 내 HWP/HWPX 파일 목록 |
-| `hwp_open_document` | HWP 문서 열기 (자동 백업) |
-| `hwp_close_document` | 문서 닫기 |
-| `hwp_save_document` | 문서 저장 (HWP/HWPX/PDF/DOCX) |
-| `hwp_export_pdf` | PDF 내보내기 |
+| hwp_check_setup | Python/pyhwpx/한글 설치 상태 자동 진단 |
+| hwp_list_files | 디렉토리 내 HWP/HWPX 파일 목록 |
+| hwp_open_document | HWP 문서 열기 (자동 백업) |
+| hwp_close_document | 문서 닫기 |
+| hwp_save_document | 문서 저장 (HWP/HWPX/PDF/DOCX) |
+| hwp_export_pdf | PDF 내보내기 |
 
 ### 문서 분석 (16개)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_analyze_document` | 전체 구조 분석 (표, 필드, 텍스트) |
-| `hwp_get_document_text` | 문서 전문 텍스트 추출 |
-| `hwp_get_document_info` | 페이지수, 파일 정보 등 메타데이터 |
-| `hwp_get_tables` | 표 데이터 조회 |
-| `hwp_map_table_cells` | 표 셀 탭 인덱스 매핑 (병합 셀 대응) |
-| `hwp_get_cell_format` | 특정 셀의 서식 정보 |
-| `hwp_get_table_format_summary` | 표 전체 서식 요약 |
-| `hwp_get_fields` | 양식 필드 목록 |
-| `hwp_get_as_markdown` | 문서를 마크다운으로 변환 |
-| `hwp_get_page_text` | 특정 페이지 텍스트 추출 |
-| `hwp_text_search` | 텍스트 검색 |
-| `hwp_form_detect` | 양식 빈칸/체크박스 자동 감지 |
-| `hwp_extract_style_profile` | 양식 서식 프로파일 추출 |
-| `hwp_image_extract` | 문서 내 이미지 추출 |
-| `hwp_document_split` | 페이지별 문서 분할 |
-| `hwp_read_reference` | 참고자료 읽기 (Excel/CSV/TXT/JSON) |
+| hwp_analyze_document | 전체 구조 분석 (표, 필드, 텍스트) |
+| hwp_get_document_text | 문서 전문 텍스트 추출 |
+| hwp_get_document_info | 페이지수, 파일 정보 등 메타데이터 |
+| hwp_get_tables | 표 데이터 조회 |
+| hwp_map_table_cells | 표 셀 탭 인덱스 매핑 (병합 셀 대응) |
+| hwp_get_cell_format | 특정 셀의 서식 정보 |
+| hwp_get_table_format_summary | 표 전체 서식 요약 |
+| hwp_get_fields | 양식 필드 목록 |
+| hwp_get_as_markdown | 문서를 마크다운으로 변환 |
+| hwp_get_page_text | 특정 페이지 텍스트 추출 |
+| hwp_text_search | 텍스트 검색 |
+| hwp_form_detect | 양식 빈칸/체크박스 자동 감지 |
+| hwp_extract_style_profile | 양식 서식 프로파일 추출 |
+| hwp_image_extract | 문서 내 이미지 추출 |
+| hwp_document_split | 페이지별 문서 분할 |
+| hwp_read_reference | 참고자료 읽기 (Excel/CSV/TXT/JSON) |
 
 ### 텍스트 편집 (18개)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_insert_text` | 텍스트 삽입 (색상/볼드/서식 지정) |
-| `hwp_insert_markdown` | 마크다운 → HWP 서식 변환 삽입 |
-| `hwp_insert_heading` | 제목 삽입 (H1~H6 + 자동 순번) |
-| `hwp_find_replace` | 찾기/바꾸기 |
-| `hwp_find_replace_multi` | 다건 찾기/바꾸기 |
-| `hwp_find_replace_nth` | N번째 항목만 찾기/바꾸기 |
-| `hwp_find_and_append` | 특정 텍스트 뒤에 내용 추가 |
-| `hwp_set_paragraph_style` | 문단 서식 설정 (정렬, 줄간격, 들여쓰기) |
-| `hwp_indent` | 들여쓰기 |
-| `hwp_outdent` | 내어쓰기 |
-| `hwp_insert_page_break` | 페이지 나누기 |
-| `hwp_insert_page_num` | 쪽 번호 삽입 (형식 지정) |
-| `hwp_insert_date_code` | 날짜 자동 삽입 |
-| `hwp_insert_footnote` | 각주 삽입 |
-| `hwp_insert_endnote` | 미주 삽입 |
-| `hwp_insert_hyperlink` | 하이퍼링크 삽입 |
-| `hwp_insert_auto_num` | 자동 번호매기기 |
-| `hwp_insert_memo` | 메모 삽입 |
+| hwp_insert_text | 텍스트 삽입 (색상/볼드/서식) |
+| hwp_insert_markdown | 마크다운을 HWP 서식으로 변환 삽입 |
+| hwp_insert_heading | 제목 삽입 (H1~H6 + 자동 순번) |
+| hwp_find_replace | 찾기/바꾸기 |
+| hwp_find_replace_multi | 다건 찾기/바꾸기 |
+| hwp_find_replace_nth | N번째 항목만 찾기/바꾸기 |
+| hwp_find_and_append | 특정 텍스트 뒤에 내용 추가 |
+| hwp_set_paragraph_style | 문단 서식 (정렬, 줄간격, 들여쓰기) |
+| hwp_indent | 들여쓰기 |
+| hwp_outdent | 내어쓰기 |
+| hwp_insert_page_break | 페이지 나누기 |
+| hwp_insert_page_num | 쪽 번호 삽입 |
+| hwp_insert_date_code | 날짜 자동 삽입 |
+| hwp_insert_footnote | 각주 삽입 |
+| hwp_insert_endnote | 미주 삽입 |
+| hwp_insert_hyperlink | 하이퍼링크 삽입 |
+| hwp_insert_auto_num | 자동 번호매기기 |
+| hwp_insert_memo | 메모 삽입 |
 
 ### 표 편집 (18개)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_fill_table_cells` | 표 셀 채우기 (탭/라벨/좌표 기반) |
-| `hwp_fill_fields` | 양식 필드 채우기 |
-| `hwp_table_create_from_data` | 2D 배열로 표 생성 (헤더 자동 스타일링) |
-| `hwp_table_insert_from_csv` | CSV/Excel에서 표 생성 |
-| `hwp_table_add_row` | 행 추가 |
-| `hwp_table_add_column` | 열 추가 |
-| `hwp_table_delete_row` | 행 삭제 |
-| `hwp_table_delete_column` | 열 삭제 |
-| `hwp_table_merge_cells` | 셀 병합 |
-| `hwp_table_split_cell` | 셀 분할 |
-| `hwp_table_distribute_width` | 셀 너비 균등 분배 |
-| `hwp_table_swap_type` | 행/열 교환 |
-| `hwp_table_formula_sum` | 합계 수식 |
-| `hwp_table_formula_avg` | 평균 수식 |
-| `hwp_table_to_csv` | 표 → CSV 내보내기 |
-| `hwp_table_to_json` | 표 → JSON 내보내기 |
-| `hwp_set_cell_color` | 셀 배경색 설정 |
-| `hwp_set_table_border` | 표 테두리 스타일 설정 |
+| hwp_fill_table_cells | 표 셀 채우기 (탭/라벨/좌표) |
+| hwp_fill_fields | 양식 필드 채우기 |
+| hwp_table_create_from_data | 2D 배열로 표 생성 |
+| hwp_table_insert_from_csv | CSV/Excel에서 표 생성 |
+| hwp_table_add_row | 행 추가 |
+| hwp_table_add_column | 열 추가 |
+| hwp_table_delete_row | 행 삭제 |
+| hwp_table_delete_column | 열 삭제 |
+| hwp_table_merge_cells | 셀 병합 |
+| hwp_table_split_cell | 셀 분할 |
+| hwp_table_distribute_width | 셀 너비 균등 분배 |
+| hwp_table_swap_type | 행/열 교환 |
+| hwp_table_formula_sum | 합계 수식 |
+| hwp_table_formula_avg | 평균 수식 |
+| hwp_table_to_csv | 표를 CSV로 내보내기 |
+| hwp_table_to_json | 표를 JSON으로 내보내기 |
+| hwp_set_cell_color | 셀 배경색 설정 |
+| hwp_set_table_border | 표 테두리 스타일 설정 |
 
 ### 이미지/레이아웃 (5개)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_insert_picture` | 이미지 삽입 |
-| `hwp_set_background_picture` | 배경 이미지 설정 |
-| `hwp_insert_line` | 선(줄) 삽입 |
-| `hwp_break_section` | 섹션 나누기 |
-| `hwp_break_column` | 다단 나누기 |
+| hwp_insert_picture | 이미지 삽입 |
+| hwp_set_background_picture | 배경 이미지 설정 |
+| hwp_insert_line | 선(줄) 삽입 |
+| hwp_break_section | 섹션 나누기 |
+| hwp_break_column | 다단 나누기 |
 
-### 스마트/복합 도구 (14개)
+### 스마트/복합 도구 (16개)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_smart_analyze` | AI용 심층 분석 (문서 유형 추론 + 서식 프로파일) |
-| `hwp_smart_fill` | 기존 서식 감지 후 보존하며 채우기 |
-| `hwp_auto_fill_from_reference` | 참고자료(Excel) → 자동 매핑 → 채우기 |
-| `hwp_auto_map_reference` | 참고자료 헤더 ↔ 표 라벨 자동 매핑 |
-| `hwp_generate_multi_documents` | 다건 문서 일괄 생성 |
-| `hwp_generate_toc` | 목차 자동 생성 |
-| `hwp_create_gantt_chart` | 간트차트 추진일정 표 생성 |
-| `hwp_document_merge` | 여러 문서 병합 |
-| `hwp_document_summary` | 문서 요약 정보 |
-| `hwp_privacy_scan` | 개인정보(주민번호, 전화번호 등) 자동 감지 |
-| `hwp_batch_convert` | 폴더 내 HWP 일괄 변환 |
-| `hwp_compare_documents` | 두 문서 비교 |
-| `hwp_word_count` | 글자수/단어수/페이지수 |
-| `hwp_delete_guide_text` | 작성요령/가이드 텍스트 자동 삭제 |
-
-### 양식 도구 (2개)
-
-| 도구 | 설명 |
-|------|------|
-| `hwp_toggle_checkbox` | 체크박스 전환 (□→■) |
-| `hwp_inspect_com_object` | [개발용] COM 객체 속성 조회 |
+| hwp_smart_analyze | AI용 심층 분석 (문서 유형 추론) |
+| hwp_smart_fill | 서식 감지 후 보존하며 채우기 |
+| hwp_auto_fill_from_reference | Excel에서 자동 매핑 후 채우기 |
+| hwp_auto_map_reference | 참고자료 헤더와 표 라벨 자동 매핑 |
+| hwp_generate_multi_documents | 다건 문서 일괄 생성 |
+| hwp_generate_toc | 목차 자동 생성 |
+| hwp_create_gantt_chart | 간트차트 추진일정 표 생성 |
+| hwp_document_merge | 여러 문서 병합 |
+| hwp_document_summary | 문서 요약 정보 |
+| hwp_privacy_scan | 개인정보 자동 감지 |
+| hwp_batch_convert | HWP 일괄 변환 |
+| hwp_compare_documents | 두 문서 비교 |
+| hwp_word_count | 글자수/단어수/페이지수 |
+| hwp_delete_guide_text | 작성요령 자동 삭제 |
+| hwp_toggle_checkbox | 체크박스 전환 |
+| hwp_inspect_com_object | [개발용] COM 객체 속성 조회 |
 
 ### HWPX 도구 (4개, 한글 프로그램 없이 동작)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_template_list` | 문서 템플릿 목록 (22종) |
-| `hwp_document_create` | 빈 HWPX 문서 생성 |
-| `hwp_template_generate` | 템플릿 기반 문서 생성 |
-| `hwp_xml_edit_text` | HWPX XML 직접 텍스트 편집 |
+| hwp_template_list | 문서 템플릿 목록 (22종) |
+| hwp_document_create | 빈 HWPX 문서 생성 |
+| hwp_template_generate | 템플릿 기반 문서 생성 |
+| hwp_xml_edit_text | HWPX XML 직접 텍스트 편집 |
 
 ### 내보내기 (2개)
 
 | 도구 | 설명 |
 |------|------|
-| `hwp_export_docx` | DOCX(Word) 내보내기 |
-| `hwp_export_html` | HTML 내보내기 |
-
----
-
-## 아키텍처
-
-```
-Claude Code / Claude Desktop
-    ↓ MCP Protocol (stdio)
-MCP Server (Node.js/TypeScript)
-    ├── document-tools.ts    (문서 관리 6개)
-    ├── analysis-tools.ts    (분석 16개)
-    ├── editing-tools.ts     (편집 51개)
-    └── composite-tools.ts   (복합 20개)
-         ↓ child_process (JSON stdin/stdout)
-    Python Bridge (hwp_service.py)
-    ├── hwp_editor.py        (편집 함수)
-    ├── hwp_analyzer.py      (분석 함수)
-    ├── privacy_scanner.py   (개인정보 스캔)
-    └── ref_reader.py        (참고자료 리더)
-         ↓ COM API
-    한글(HWP) 프로그램
-```
-
-- **MCP 서버**: TypeScript, `@modelcontextprotocol/sdk` 기반
-- **Python 브릿지**: pyhwpx를 통한 COM API 제어
-- **HWPX 엔진**: `@xmldom/xmldom` + `jszip`으로 XML 직접 편집 (한글 프로그램 없이)
+| hwp_export_docx | DOCX(Word) 내보내기 |
+| hwp_export_html | HTML 내보내기 |
 
 ---
 
 ## Toolset 모드
 
-토큰 사용량을 줄이려면 `--toolset` 옵션을 사용하세요:
+토큰 절약이 필요하면 minimal 모드를 사용하세요 (15개 핵심 도구만 로드):
 
-| 모드 | 도구 수 | 용도 |
-|------|---------|------|
-| `minimal` | 15개 | 토큰 절약. 문서 열기/닫기, 표 채우기, 찾기/바꾸기 등 핵심만 |
-| `standard` | 85개+ | 전체 기능 (기본값) |
-
-```bash
-hwp-mcp --toolset=minimal
+```json
+{
+  "mcpServers": {
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp",
+      "args": ["--toolset=minimal"]
+    }
+  }
+}
 ```
 
 ---
 
-## 문제 해결
-
-### "Python을 찾을 수 없습니다"
-
-```bash
-# Python이 PATH에 있는지 확인
-python --version
-
-# 없다면 python.org에서 설치 (Add to PATH 체크)
-# 설치 후 터미널을 다시 열어야 합니다
-```
-
-### "pyhwpx 모듈을 찾을 수 없습니다"
-
-```bash
-pip install pyhwpx pywin32
-```
-
-### "COM class not registered"
-
-한글(HWP) 프로그램이 설치되어 있지 않거나 COM 등록이 안 된 상태입니다.
-- 한컴오피스 한글을 설치하세요
-- 설치 후 한글을 한번 실행하여 초기 설정을 완료하세요
-
-### "RPC 서버를 사용할 수 없습니다"
-
-한글 프로그램이 응답하지 않는 상태입니다.
-- 한글을 닫고 다시 시도하세요
-- 작업 관리자에서 `HWP.exe` 프로세스가 남아있다면 종료하세요
-
-### 자동 진단
+## 아키텍처
 
-Claude에게 요청하세요:
 ```
-"hwp_check_setup 실행해줘"
+Claude Code / Claude Desktop
+    |  MCP Protocol (stdio)
+MCP Server (Node.js/TypeScript)
+    |  child_process (JSON stdin/stdout)
+Python Bridge (hwp_service.py + pyhwpx)
+    |  COM API
+한글(HWP) 프로그램
 ```
-→ Python, pyhwpx, 한글 설치 상태를 자동으로 확인하고 안내합니다.
 
 ---
 
 ## 지원 한글 버전
 
-| 한글 버전 | 지원 |
-|-----------|------|
-| 한글 2014 | ✅ |
-| 한글 2018 | ✅ |
-| 한글 2020 | ✅ |
-| 한글 2022 | ✅ |
-| 한글 2024 | ✅ |
+한글 2014, 2018, 2020, 2022, 2024 모두 지원합니다.
 
 ---
 
@@ -399,8 +469,6 @@ Claude에게 요청하세요:
 
 MIT License
 
----
-
 ## 관련 링크
 
 - [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)

package/dist/hwp-bridge.d.ts

@@ -16,6 +16,7 @@ export interface PrerequisiteResult {
     python: {
         found: boolean;
         version?: string;
+        path?: string;
         error?: string;
         guide?: string;
     };
@@ -30,6 +31,7 @@ export interface PrerequisiteResult {
         error?: string;
         guide?: string;
     };
+    hwpRunning: boolean;
     os: {
         ok: boolean;
         platform: string;

package/dist/hwp-bridge.js

@@ -235,6 +235,7 @@ export class HwpBridge {
             python: { found: false },
             pyhwpx: { found: false },
             hwp: { found: false },
+            hwpRunning: false,
             os: { ok: process.platform === 'win32', platform: process.platform },
         };
         if (!result.os.ok) {
@@ -242,16 +243,26 @@ export class HwpBridge {
             return result;
         }
         const pythonExe = this.findPython();
-        // 1) Python 체크
+        // 1) Python 체크 — 경로 + 버전 + Microsoft Store 감지
         try {
-            const { stdout } = await execFileAsync(pythonExe, ['--version'], { timeout: 5000 });
-            const ver = stdout.trim().replace('Python ', '');
-            result.python = { found: true, version: ver };
+            const { stdout } = await execFileAsync(pythonExe, ['-c', 'import sys; print(sys.version.split()[0]); print(sys.executable)'], { timeout: 5000 });
+            const lines = stdout.trim().split(/\r?\n/);
+            const ver = lines[0];
+            const exePath = lines[1] || '';
+            const isStorePython = exePath.includes('WindowsApps');
+            result.python = {
+                found: true,
+                version: ver,
+                path: exePath,
+                guide: isStorePython
+                    ? `Microsoft Store Python 감지 (${exePath}). pyhwpx가 인식되지 않을 수 있습니다.\n→ python.org에서 재설치를 권장합니다: https://www.python.org/downloads/`
+                    : undefined,
+            };
         }
         catch {
             result.python = {
                 found: false,
-                guide: 'Python 3.8+ 설치 필요\n→ https://www.python.org/downloads/\n→ 설치 시 "Add Python to PATH" 반드시 체크\n→ 설치 후 터미널 재시작',
+                guide: 'Python 3.8+ 설치 필요\n→ https://www.python.org/downloads/ 에서 설치\n→ 설치 시 "Add Python to PATH" 반드시 체크\n→ Microsoft Store 버전이 아닌 python.org 공식 버전 권장\n→ 설치 후 터미널 재시작',
             };
             return result;
         }
@@ -263,7 +274,7 @@ export class HwpBridge {
         catch {
             result.pyhwpx = {
                 found: false,
-                guide: 'pyhwpx 패키지 설치 필요\n→ 터미널에서 실행: pip install pyhwpx\n→ pywin32도 함께 필요: pip install pywin32',
+                guide: `pyhwpx 패키지 설치 필요\n→ 감지된 Python: ${result.python.path || pythonExe}\n→ 터미널에서 실행: pip install pyhwpx pywin32`,
             };
             return result;
         }
@@ -281,10 +292,17 @@ export class HwpBridge {
                 };
             }
             else {
-                // COM은 등록되어 있지만 다른 에러 (이미 실행 중 등) → 설치는 된 것
                 result.hwp = { found: true };
             }
         }
+        // 4) 한글 프로세스 실행 여부 체크
+        try {
+            const { stdout } = await execFileAsync('tasklist', ['/FI', 'IMAGENAME eq Hwp.exe', '/NH'], { timeout: 5000 });
+            result.hwpRunning = stdout.includes('Hwp.exe');
+        }
+        catch {
+            result.hwpRunning = false;
+        }
         result.ok = result.python.found && result.pyhwpx.found && result.hwp.found;
         return result;
     }

package/dist/index.js

@@ -19,8 +19,8 @@ const resolvedToolset = validToolsets.includes(toolset)
     : 'standard';
 const bridge = new HwpBridge();
 const server = new McpServer({
-    name: 'hwp-studio',
-    version: '0.2.0',
+    name: 'claude-code-hwp-mcp',
+    version: '0.2.2',
 });
 setupServer(server, bridge, resolvedToolset);
 const transport = new StdioServerTransport();

package/dist/tools/document-tools.js

@@ -87,7 +87,10 @@ export function registerDocumentTools(server, bridge) {
                 items.push(`❌ OS: ${prereq.os.error}`);
             }
             if (prereq.python.found) {
-                items.push(`✅ Python ${prereq.python.version}`);
+                let pyInfo = `✅ Python ${prereq.python.version} (${prereq.python.path || 'unknown'})`;
+                if (prereq.python.guide)
+                    pyInfo += `\n   ⚠️ ${prereq.python.guide}`;
+                items.push(pyInfo);
             }
             else {
                 items.push(`❌ Python 미설치\n   ${prereq.python.guide}`);
@@ -99,16 +102,28 @@ export function registerDocumentTools(server, bridge) {
                 items.push(`❌ pyhwpx 미설치\n   ${prereq.pyhwpx.guide}`);
             }
             if (prereq.hwp.found) {
-                items.push('✅ 한글(HWP) 프로그램');
+                items.push('✅ 한글(HWP) 프로그램 설치됨');
             }
             else if (prereq.pyhwpx.found) {
                 items.push(`❌ 한글(HWP) 미설치\n   ${prereq.hwp.guide}`);
             }
+            // 한글 실행 여부
+            if (prereq.hwp.found) {
+                if (prereq.hwpRunning) {
+                    items.push('✅ 한글(HWP) 실행 중');
+                }
+                else {
+                    items.push('⚠️ 한글(HWP)이 실행되지 않았습니다. 문서 작업 전 한글을 먼저 실행하세요.');
+                }
+            }
+            const allReady = prereq.ok && prereq.hwpRunning;
             return { content: [{ type: 'text', text: JSON.stringify({
-                            status: prereq.ok ? 'ready' : 'not_ready',
-                            message: prereq.ok
+                            status: allReady ? 'ready' : prereq.ok ? 'hwp_not_running' : 'not_ready',
+                            message: allReady
                                 ? '모든 요구사항이 충족되었습니다. HWP 도구를 사용할 수 있습니다.'
-                                : '아래 항목을 설치한 후 다시 시도하세요.',
+                                : prereq.ok
+                                    ? '한글(HWP) 프로그램을 실행한 후 다시 시도하세요.'
+                                    : '아래 항목을 설치한 후 다시 시도하세요.',
                             details: prereq,
                             summary: items.join('\n'),
                         }) }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hwp-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "MCP server for HWP (한글) document automation via pyhwpx COM API. 85+ tools for document editing, analysis, and AI-powered filling.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,10 +9,12 @@
   },
   "files": [
     "dist/",
-    "python/"
+    "python/*.py",
+    "python/requirements.txt"
   ],
   "scripts": {
     "build": "tsc",
+    "postinstall": "node -e \"try{require('child_process').execSync('python -c \\\"import pyhwpx\\\"',{stdio:'ignore'})}catch{console.log('\\n[claude-code-hwp-mcp] pyhwpx 미설치. 실행하세요: pip install pyhwpx pywin32\\n')}\"",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"