claude-code-hwp-mcp 0.2.0 → 0.2.1

package/README.md

@@ -1,49 +1,57 @@
 # claude-code-hwp-mcp
 
-Claude Code에서 한글(HWP) 문서를 직접 제어하는 MCP 서버입니다.
+Claude Code / Claude Desktop에서 한글(HWP) 문서를 직접 제어하는 MCP 서버.
 pyhwpx COM API를 통해 문서 열기, 편집, 분석, 저장, 변환까지 **85개+ 도구**를 제공합니다.
 
-> **Windows 전용** | 한글(HWP) 2014 이상 | Python 3.8+ | Claude Code / Claude Desktop 지원
+> **Windows 전용** | 한글 2014 이상 | Python 3.8+ | Claude Code & Claude Desktop 지원
 
----
+## 빠른 시작
 
-## 목차
+```bash
+# 1. Python 패키지 설치
+pip install pyhwpx pywin32
 
-- [설치 방법](#설치-방법)
-- [Claude Code 설정](#claude-code-설정)
-- [Claude Desktop 설정](#claude-desktop-설정)
-- [사용 방법](#사용-방법)
-- [기능 목록 (85개+)](#기능-목록-85개)
-- [아키텍처](#아키텍처)
-- [문제 해결](#문제-해결)
+# 2. MCP 서버 설치
+npm install -g claude-code-hwp-mcp
 
----
+# 3. 한글(HWP) 프로그램을 실행하고 빈 문서를 열어둡니다
+
+# 4. Claude Code 또는 Claude Desktop에서 사용
+```
 
-## 설치 방법
+## 사전 요구사항
 
-### 1단계: 사전 요구사항 설치
+| 요구사항 | 설치 방법 | 비고 |
+|----------|-----------|------|
+| Windows 10/11 | - | macOS/Linux 미지원 (COM API 기반) |
+| 한글(HWP) | 한컴오피스 설치 | 한글 2014, 2018, 2020, 2022, 2024 지원 |
+| Python 3.8+ | [python.org](https://www.python.org/downloads/) | **반드시 python.org에서 설치** |
+| Node.js 18+ | [nodejs.org](https://nodejs.org/) | LTS 버전 권장 |
 
-| 요구사항 | 설치 방법 |
-|----------|-----------|
-| **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 버전 설치 |
+### Python 설치 시 주의사항
 
-### 2단계: Python 패키지 설치
+**python.org 공식 버전을 설치하세요.** Microsoft Store 버전(WindowsApps 경로)은 pyhwpx가 정상 동작하지 않을 수 있습니다.
 
+설치 화면에서 **"Add Python to PATH"를 반드시 체크**하세요.
+
+설치 확인:
 ```bash
-pip install pyhwpx pywin32
+python --version
+pip show pyhwpx
 ```
 
-### 3단계: MCP 서버 설치
+## 설치
+
+### 방법 A: npm 글로벌 설치 (권장)
 
-**방법 A: npm 글로벌 설치 (권장)**
 ```bash
 npm install -g claude-code-hwp-mcp
 ```
 
-**방법 B: GitHub에서 직접 클론**
+설치 후 pyhwpx가 없으면 자동으로 안내 메시지가 표시됩니다.
+
+### 방법 B: GitHub 클론
+
 ```bash
 git clone https://github.com/gmlcjf0326/claude-code-hwp-mcp.git
 cd claude-code-hwp-mcp
@@ -51,356 +59,274 @@ npm install
 npm run build
 ```
 
-### 4단계: 환경 확인
-
-설치 후 `hwp_check_setup` 도구를 호출하면 환경을 자동 진단합니다:
-```
-✅ Python 3.11.5
-✅ pyhwpx installed
-✅ 한글(HWP) 프로그램
-→ 모든 요구사항이 충족되었습니다.
-```
-
----
-
 ## Claude Code 설정
 
-`~/.claude/settings.json`에 MCP 서버를 등록합니다:
+`~/.claude/settings.json` 파일에 추가:
 
-**npm 글로벌 설치한 경우:**
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
-      "command": "hwp-mcp",
-      "args": []
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp"
     }
   }
 }
 ```
 
-**GitHub 클론한 경우:**
+GitHub 클론 방식:
+
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
+    "claude-code-hwp-mcp": {
       "command": "node",
-      "args": ["C:/경로/claude-code-hwp-mcp/dist/index.js"]
+      "args": ["C:/claude-code-hwp-mcp/dist/index.js"]
     }
   }
 }
 ```
 
-**토큰 절약 모드 (도구 15개만 로드):**
+Python 경로를 직접 지정하려면:
+
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
+    "claude-code-hwp-mcp": {
       "command": "hwp-mcp",
-      "args": ["--toolset=minimal"]
+      "env": {
+        "PYTHON_PATH": "C:/Python313/python.exe"
+      }
     }
   }
 }
 ```
 
----
-
 ## Claude Desktop 설정
 
-`claude_desktop_config.json`에 추가:
+`%APPDATA%\Claude\claude_desktop_config.json` 파일에 추가:
 
 ```json
 {
   "mcpServers": {
-    "hwp-studio": {
-      "command": "hwp-mcp",
-      "args": []
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp"
     }
   }
 }
 ```
 
-설정 파일 위치:
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+## 사용 전 반드시 확인
 
----
+**한글(HWP) 프로그램이 실행 중이어야 합니다.** MCP 서버는 한글 프로그램의 COM API를 통해 문서를 제어하므로, 한글이 열려 있지 않으면 도구가 동작하지 않습니다.
 
-## 사용 방법
+1. 한글(HWP) 프로그램 실행
+2. 빈 문서 하나 열어두기
+3. Claude에서 작업 시작
 
-### 기본 흐름
+환경 진단이 필요하면:
+```
+"hwp_check_setup 실행해줘"
+```
 
-Claude Code에서 자연어로 요청하면 됩니다:
+## 사용 예시
 
 ```
 "C:/문서/사업계획서.hwp 파일을 열어서 분석해줘"
 "표의 계약금액 칸에 50,000,000원을 채워줘"
 "문서를 PDF로 변환해줘"
-```
-
-### 예시: 공문서 양식 채우기
-
-```
-1. "C:/양식/과업지시서.hwp 열어줘"
-2. "문서 구조를 분석해줘"
-3. "표에서 '사업명' 칸에 'AI 문서 자동화 프로젝트'를 채워줘"
-4. "작성요령 텍스트 삭제해줘"
-5. "저장하고 PDF로도 내보내줘"
-```
-
-### 예시: 엑셀 데이터로 자동 채우기
-
-```
+"작성요령 텍스트 삭제해줘"
 "참고자료.xlsx를 읽어서 양식.hwp의 표를 자동으로 채워줘"
-```
-→ `hwp_auto_fill_from_reference` 도구가 엑셀 헤더를 표 라벨과 자동 매칭합니다.
-
-### 예시: 다건 문서 생성
-
-```
 "직원_명단.xlsx의 각 행으로 위촉장.hwp를 개별 생성해줘"
 ```
-→ `hwp_generate_multi_documents`가 행마다 별도 HWP 파일을 생성합니다.
-
----
 
 ## 기능 목록 (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` | 다단 나누기 |
-
-### 스마트/복합 도구 (14개)
+| hwp_insert_picture | 이미지 삽입 |
+| hwp_set_background_picture | 배경 이미지 설정 |
+| hwp_insert_line | 선(줄) 삽입 |
+| hwp_break_section | 섹션 나누기 |
+| hwp_break_column | 다단 나누기 |
 
-| 도구 | 설명 |
-|------|------|
-| `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개)
+### 스마트/복합 도구 (16개)
 
 | 도구 | 설명 |
 |------|------|
-| `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 내보내기 |
-
----
+| hwp_export_docx | DOCX(Word) 내보내기 |
+| hwp_export_html | HTML 내보내기 |
 
 ## 아키텍처
 
 ```
 Claude Code / Claude Desktop
-    ↓ MCP Protocol (stdio)
+    |  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) 프로그램
+    |  child_process (JSON stdin/stdout)
+Python Bridge (hwp_service.py + pyhwpx)
+    |  COM API
+한글(HWP) 프로그램
 ```
 
-- **MCP 서버**: TypeScript, `@modelcontextprotocol/sdk` 기반
-- **Python 브릿지**: pyhwpx를 통한 COM API 제어
-- **HWPX 엔진**: `@xmldom/xmldom` + `jszip`으로 XML 직접 편집 (한글 프로그램 없이)
-
----
-
 ## 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을 찾을 수 없습니다"
+### Python을 찾을 수 없습니다
 
-```bash
-# Python이 PATH에 있는지 확인
-python --version
-
-# 없다면 python.org에서 설치 (Add to PATH 체크)
-# 설치 후 터미널을 다시 열어야 합니다
-```
+python.org에서 Python 3.8+을 설치하세요. 설치 시 "Add Python to PATH" 체크 필수.
+Microsoft Store 버전은 권장하지 않습니다.
 
-### "pyhwpx 모듈을 찾을 수 없습니다"
+### pyhwpx 모듈을 찾을 수 없습니다
 
 ```bash
 pip install pyhwpx pywin32
 ```
 
-### "COM class not registered"
+여러 Python이 설치된 경우 경로를 확인하세요:
+```bash
+python -c "import sys; print(sys.executable)"
+```
 
-한글(HWP) 프로그램이 설치되어 있지 않거나 COM 등록이 안 된 상태입니다.
-- 한컴오피스 한글을 설치하세요
-- 설치 후 한글을 한번 실행하여 초기 설정을 완료하세요
+### COM class not registered
 
-### "RPC 서버를 사용할 수 없습니다"
+한컴오피스 한글을 설치하세요. 설치 후 한글을 한번 실행하여 초기 설정을 완료하세요.
 
-한글 프로그램이 응답하지 않는 상태입니다.
-- 한글을 닫고 다시 시도하세요
-- 작업 관리자에서 `HWP.exe` 프로세스가 남아있다면 종료하세요
+### RPC 서버를 사용할 수 없습니다
 
-### 자동 진단
+한글을 닫고 다시 시도하세요. 작업 관리자에서 Hwp.exe 프로세스가 남아있으면 종료하세요.
 
-Claude에게 요청하세요:
-```
-"hwp_check_setup 실행해줘"
-```
-→ Python, pyhwpx, 한글 설치 상태를 자동으로 확인하고 안내합니다.
+### 한글이 열려있는데도 안 됩니다
 
----
-
-## 지원 한글 버전
-
-| 한글 버전 | 지원 |
-|-----------|------|
-| 한글 2014 | ✅ |
-| 한글 2018 | ✅ |
-| 한글 2020 | ✅ |
-| 한글 2022 | ✅ |
-| 한글 2024 | ✅ |
-
----
+한글 프로그램이 실행 중이어야 COM 연결이 됩니다. hwp_check_setup으로 진단하세요.
 
 ## 라이선스
 
 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.1',
 });
 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.1",
   "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"