claude-code-hwp-mcp 0.2.1 → 0.3.1

package/README.md

@@ -1,67 +1,84 @@
 # claude-code-hwp-mcp
 
-Claude Code / Claude Desktop에서 한글(HWP) 문서를 직접 제어하는 MCP 서버.
-pyhwpx COM API를 통해 문서 열기, 편집, 분석, 저장, 변환까지 **85개+ 도구**를 제공합니다.
+Claude Code와 Claude Desktop에서 한글(HWP) 문서를 AI로 자동 편집하는 MCP 서버입니다.
 
-> **Windows 전용** | 한글 2014 이상 | Python 3.8+ | Claude Code & Claude Desktop 지원
+85개 이상의 도구로 문서 열기, 표 채우기, 텍스트 편집, 서식 설정, PDF 변환까지 모두 자동화할 수 있습니다.
 
-## 빠른 시작
+> Windows 전용 | 한글 2014 이상 | Python 3.8+ | Claude Code + Claude Desktop 지원
 
-```bash
-# 1. Python 패키지 설치
-pip install pyhwpx pywin32
+---
 
-# 2. MCP 서버 설치
-npm install -g claude-code-hwp-mcp
+## 설치 가이드 (처음 설정하는 분)
 
-# 3. 한글(HWP) 프로그램을 실행하고 빈 문서를 열어둡니다
+아래 순서대로 따라하세요. 5분이면 완료됩니다.
 
-# 4. Claude Code 또는 Claude Desktop에서 사용
-```
+### Step 1. Python 설치
+
+**반드시 python.org 공식 버전을 설치하세요.**
+
+1. https://www.python.org/downloads/ 에 접속
+2. "Download Python 3.x.x" 버튼 클릭
+3. 설치 화면에서 **"Add Python to PATH" 체크박스를 반드시 체크**
+4. "Install Now" 클릭
 
-## 사전 요구사항
+> **Microsoft Store 버전 Python은 사용하지 마세요.** Store 버전은 패키지가 격리된 경로에 설치되어 pyhwpx를 인식하지 못합니다. 이미 Store 버전이 설치되어 있다면 [Microsoft Store Python 문제 해결](#microsoft-store-python-문제) 섹션을 참고하세요.
 
-| 요구사항 | 설치 방법 | 비고 |
-|----------|-----------|------|
-| 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 버전 권장 |
+설치 확인 (명령 프롬프트에서):
 
-### Python 설치 시 주의사항
+```bash
+python --version
+```
 
-**python.org 공식 버전을 설치하세요.** Microsoft Store 버전(WindowsApps 경로)은 pyhwpx가 정상 동작하지 않을 수 있습니다.
+`Python 3.x.x`가 출력되면 성공입니다.
 
-설치 화면에서 **"Add Python to PATH"를 반드시 체크**하세요.
+### Step 2. Python 패키지 설치
+
+명령 프롬프트(cmd)를 열고 아래를 실행하세요:
+
+```bash
+pip install pyhwpx pywin32
+```
 
 설치 확인:
+
 ```bash
-python --version
 pip show pyhwpx
 ```
 
-## 설치
+### Step 3. Node.js 설치
+
+1. https://nodejs.org/ 에 접속
+2. LTS 버전 다운로드 후 설치
+
+### Step 4. MCP 서버 설치
 
-### 방법 A: npm 글로벌 설치 (권장)
+명령 프롬프트에서:
 
 ```bash
 npm install -g claude-code-hwp-mcp
 ```
 
-설치 후 pyhwpx가 없으면 자동으로 안내 메시지가 표시됩니다.
+### Step 5. Claude에 MCP 서버 연결
 
-### 방법 B: GitHub 클론
+사용하는 Claude 앱에 따라 아래 설정을 진행하세요:
 
-```bash
-git clone https://github.com/gmlcjf0326/claude-code-hwp-mcp.git
-cd claude-code-hwp-mcp
-npm install
-npm run build
-```
+- **Claude Code** 사용자 → [Claude Code 설정](#claude-code-설정) 섹션으로
+- **Claude Desktop** 사용자 → [Claude Desktop 설정](#claude-desktop-설정) 섹션으로
+
+---
 
 ## Claude Code 설정
 
-`~/.claude/settings.json` 파일에 추가:
+### 설정 파일 열기
+
+Claude Code 터미널에서 설정 파일을 엽니다. 파일 위치:
+
+- Windows: `C:\Users\사용자이름\.claude\settings.json`
+- 또는 `~/.claude/settings.json`
+
+### 설정 추가
+
+`settings.json` 파일에 아래 내용을 추가하세요:
 
 ```json
 {
@@ -73,37 +90,63 @@ npm run build
 }
 ```
 
-GitHub 클론 방식:
+이미 다른 MCP 서버가 등록되어 있다면 `mcpServers` 안에 추가합니다:
 
 ```json
 {
   "mcpServers": {
+    "기존-서버": {
+      "command": "기존-명령"
+    },
     "claude-code-hwp-mcp": {
-      "command": "node",
-      "args": ["C:/claude-code-hwp-mcp/dist/index.js"]
+      "command": "hwp-mcp"
     }
   }
 }
 ```
 
-Python 경로를 직접 지정하려면:
+### GitHub 클론 방식으로 설치한 경우
+
+npm 글로벌 설치 대신 GitHub에서 클론한 경우:
 
 ```json
 {
   "mcpServers": {
     "claude-code-hwp-mcp": {
-      "command": "hwp-mcp",
-      "env": {
-        "PYTHON_PATH": "C:/Python313/python.exe"
-      }
+      "command": "node",
+      "args": ["C:\\claude-code-hwp-mcp\\dist\\index.js"]
     }
   }
 }
 ```
 
+`args`의 경로를 실제 클론한 위치로 변경하세요.
+
+---
+
 ## Claude Desktop 설정
 
-`%APPDATA%\Claude\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
 {
@@ -115,21 +158,64 @@ Python 경로를 직접 지정하려면:
 }
 ```
 
-## 사용 전 반드시 확인
+### Step 4. (선택) Python 경로 직접 지정
+
+Python이 여러 개 설치되어 있거나 Microsoft Store Python 문제가 있을 경우, Python 경로를 명시적으로 지정할 수 있습니다:
+
+```json
+{
+  "mcpServers": {
+    "claude-code-hwp-mcp": {
+      "command": "hwp-mcp",
+      "env": {
+        "PYTHON_PATH": "C:\\Users\\사용자이름\\AppData\\Local\\Programs\\Python\\Python313\\python.exe"
+      }
+    }
+  }
+}
+```
+
+본인의 Python 경로를 확인하려면 명령 프롬프트에서:
 
-**한글(HWP) 프로그램이 실행 중이어야 합니다.** MCP 서버는 한글 프로그램의 COM API를 통해 문서를 제어하므로, 한글이 열려 있지 않으면 도구가 동작하지 않습니다.
+```bash
+python -c "import sys; print(sys.executable)"
+```
+
+출력된 경로를 `PYTHON_PATH` 값으로 사용하세요.
+
+### Step 5. Claude Desktop 재시작
+
+설정 파일을 저장한 후 **Claude Desktop을 완전히 종료했다가 다시 실행**하세요. (트레이에서도 완전 종료)
 
-1. 한글(HWP) 프로그램 실행
-2. 빈 문서 하나 열어두기
-3. Claude에서 작업 시작
+### Step 6. 연결 확인
+
+Claude Desktop에서 아래와 같이 입력하세요:
 
-환경 진단이 필요하면:
 ```
-"hwp_check_setup 실행해줘"
+hwp_check_setup 실행해줘
 ```
 
+모든 항목에 체크 표시가 나오면 성공입니다.
+
+---
+
+## 사용 전 반드시 확인
+
+**한글(HWP) 프로그램이 실행 중이어야 합니다.**
+
+MCP 서버는 한글 프로그램의 COM API를 통해 문서를 제어합니다. 한글이 열려 있지 않으면 문서 관련 도구가 동작하지 않습니다.
+
+사용 순서:
+1. 한글(HWP) 프로그램을 실행합니다
+2. 빈 문서가 열린 상태로 둡니다
+3. Claude Code 또는 Claude Desktop에서 작업을 시작합니다
+
+---
+
 ## 사용 예시
 
+Claude에게 자연어로 요청하면 됩니다:
+
 ```
 "C:/문서/사업계획서.hwp 파일을 열어서 분석해줘"
 "표의 계약금액 칸에 50,000,000원을 채워줘"
@@ -139,13 +225,87 @@ Python 경로를 직접 지정하려면:
 "직원_명단.xlsx의 각 행으로 위촉장.hwp를 개별 생성해줘"
 ```
 
+---
+
+## 문제 해결
+
+### Microsoft Store Python 문제
+
+**증상**: hwp_check_setup에서 "pyhwpx 미설치" 또는 "한글 미설치"로 표시되지만 실제로는 설치되어 있음
+
+**진단**: 명령 프롬프트에서 아래를 실행하세요:
+
+```bash
+python -c "import sys; print(sys.executable)"
+```
+
+출력 경로에 `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"
+      }
+    }
+  }
+}
+```
+
+### Python을 찾을 수 없습니다
+
+python.org에서 Python 3.8+을 설치하세요. 설치 시 "Add Python to PATH" 체크 필수입니다. 설치 후 명령 프롬프트를 새로 열어야 합니다.
+
+### pyhwpx 모듈을 찾을 수 없습니다
+
+```bash
+pip install pyhwpx pywin32
+```
+
+### COM class not registered
+
+한컴오피스 한글을 설치하세요. 설치 후 한글을 한번 실행하여 초기 설정을 완료하세요.
+
+### RPC 서버를 사용할 수 없습니다
+
+한글 프로그램을 닫고 다시 시도하세요. 작업 관리자(Ctrl+Shift+Esc)에서 Hwp.exe 프로세스가 남아있으면 종료 후 재시도하세요.
+
+### 환경 자동 진단
+
+Claude에게 요청하세요:
+
+```
+"hwp_check_setup 실행해줘"
+```
+
+Python 경로, pyhwpx 설치 여부, 한글 프로그램 설치 및 실행 상태를 자동으로 확인합니다.
+
+---
+
 ## 기능 목록 (85개+)
 
 ### 환경/문서 관리 (6개)
 
 | 도구 | 설명 |
 |------|------|
-| hwp_check_setup | Python/pyhwpx/한글 설치 상태 진단 |
+| hwp_check_setup | Python/pyhwpx/한글 설치 상태 자동 진단 |
 | hwp_list_files | 디렉토리 내 HWP/HWPX 파일 목록 |
 | hwp_open_document | HWP 문서 열기 (자동 백업) |
 | hwp_close_document | 문서 닫기 |
@@ -266,17 +426,7 @@ Python 경로를 직접 지정하려면:
 | hwp_export_docx | DOCX(Word) 내보내기 |
 | hwp_export_html | HTML 내보내기 |
 
-## 아키텍처
-
-```
-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) 프로그램
-```
+---
 
 ## Toolset 모드
 
@@ -293,35 +443,123 @@ Python Bridge (hwp_service.py + pyhwpx)
 }
 ```
 
-## 문제 해결
+---
 
-### Python을 찾을 수 없습니다
+## 아키텍처
+
+```
+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.org에서 Python 3.8+을 설치하세요. 설치 시 "Add Python to PATH" 체크 필수.
-Microsoft Store 버전은 권장하지 않습니다.
+---
 
-### pyhwpx 모듈을 찾을 수 없습니다
+## HWP vs HWPX 파일 형식 차이
 
-```bash
-pip install pyhwpx pywin32
+| 구분 | HWP (바이너리) | HWPX (XML 기반) |
+|------|--------------|-----------------|
+| 내부 구조 | OLE2 바이너리 | ZIP + XML |
+| 텍스트 검색 | COM API (제한적) | XML 직접 검색 (안정적) |
+| 찾기/바꾸기 | COM API (제한적) | XML 직접 치환 (안정적) |
+| 표 생성/편집 | COM API | COM API |
+| 문서 열기/저장 | COM API | COM API |
+
+**HWPX 파일 사용을 권장합니다.** HWPX 파일의 텍스트 검색/치환은 XML을 직접 조작하므로 COM API보다 안정적입니다. 한글 프로그램에서 "다른 이름으로 저장" > "HWPX" 형식으로 변환할 수 있습니다.
+
+---
+
+## 알려진 제한사항
+
+### HWP 파일의 COM 텍스트 검색
+
+HWP 바이너리 파일에서 `hwp_text_search`가 0건을 반환할 수 있습니다. 이는 한글 COM API(`HAction.Execute("FindReplace")`)의 반환값이 프로그래밍적으로 불안정한 설계 한계입니다.
+
+대안:
+- `hwp_get_document_text`로 전체 텍스트를 가져와서 직접 검색
+- 가능하면 HWPX 형식으로 변환하여 사용 (XML 검색은 안정적)
+
+### HWPX 파일 잠금
+
+한글에서 HWPX 파일을 열어둔 상태에서 XML 직접 편집을 시도하면 파일 잠금(EBUSY) 에러가 발생합니다. 이 경우 자동으로 COM 경로로 폴백합니다.
+
+---
+
+## 추천 워크플로우
+
+### 양식 채우기
+
+```
+1. hwp_open_document → 파일 열기
+2. hwp_smart_analyze → 문서 구조 파악
+3. hwp_smart_fill 또는 hwp_auto_fill_from_reference → 자동 채우기
+4. hwp_privacy_scan → 개인정보 확인
+5. hwp_save_document → 저장
 ```
 
-여러 Python이 설치된 경우 경로를 확인하세요:
-```bash
-python -c "import sys; print(sys.executable)"
+### 텍스트 치환
+
+```
+1. hwp_open_document → 파일 열기
+2. hwp_find_replace 또는 hwp_find_replace_multi → 치환
+3. hwp_save_document → 저장
 ```
 
-### COM class not registered
+### 문서 분석
 
-한컴오피스 한글을 설치하세요. 설치 후 한글을 한번 실행하여 초기 설정을 완료하세요.
+```
+1. hwp_open_document → 파일 열기
+2. hwp_analyze_document → 전체 구조 분석
+3. hwp_get_tables → 표 데이터 확인
+4. hwp_word_count → 글자수 통계
+```
 
-### RPC 서버를 사용할 수 없습니다
+---
+
+## v0.3.0 변경사항
+
+### 버그 수정 (10건)
+
+- SelectAll 문서 파괴 수정 (table_create_from_data, gantt_chart 등)
+- find_replace 전후 텍스트 비교 검증으로 개선
+- text_search 선택 영역 기반 판단으로 개선
+- find_and_append 커서 유실 수정 (Cancel → MoveRight)
+- 버퍼 오버플로우 시 개별 요청만 거부
+- XHwpMessageBoxMode 복원 (close_document)
+- insert_markdown 표 파싱 추가
+- blank_template.hwpx 프로그래밍적 생성 (파일 의존성 제거)
+- except pass → stderr 로깅 변환
+- MAX_TABLES scanned_tables 필드 분리
+
+### HWPX XML 라우팅
+
+HWPX 파일의 텍스트 검색/치환을 Node.js XML 엔진으로 직접 처리:
+- hwp_find_replace → XML replaceTextInSection
+- hwp_find_replace_multi → XML 루프 치환
+- hwp_find_replace_nth → XML N번째 치환
+- hwp_find_and_append → XML findAndAppend
+- hwp_text_search → XML searchTextInSection
+
+XML 실패 시(파일 잠금 등) COM 경로로 자동 폴백.
+
+### 환경 진단 개선
+
+- Microsoft Store Python 자동 감지 + 경고
+- 한글 프로세스 실행 여부 체크 (tasklist)
+- Python 실행 경로 표시
+- postinstall 스크립트 ESM 호환
+
+---
 
-한글을 닫고 다시 시도하세요. 작업 관리자에서 Hwp.exe 프로세스가 남아있으면 종료하세요.
+## 지원 한글 버전
 
-### 한글이 열려있는데도 안 됩니다
+한글 2014, 2018, 2020, 2022, 2024 모두 지원합니다.
 
-한글 프로그램이 실행 중이어야 COM 연결이 됩니다. hwp_check_setup으로 진단하세요.
+---
 
 ## 라이선스
 

package/dist/hwp-bridge.d.ts

@@ -63,6 +63,7 @@ export declare class HwpBridge {
     getState(): BridgeState;
     setCurrentDocument(filePath: string | null): void;
     getCurrentDocument(): string | null;
+    getCurrentDocumentFormat(): string | null;
     getCachedAnalysis(): unknown | null;
     setCachedAnalysis(data: unknown): void;
 }

package/dist/hwp-bridge.js

@@ -81,11 +81,22 @@ export class HwpBridge {
         });
         this.process.stdout?.on('data', (chunk) => {
             this.buffer += chunk.toString('utf-8');
-            // Buffer 크기 제한 (10MB) — 메모리 폭증 방지
+            // BUG-6 fix: 버퍼 초과 시 가장 오래된 대기 요청만 거부 (전체가 아닌 개별)
             if (this.buffer.length > this.MAX_BUFFER_SIZE) {
-                console.error(`[HWP MCP Bridge] Buffer exceeded ${this.MAX_BUFFER_SIZE / 1024 / 1024}MB, clearing`);
-                this.buffer = '';
-                this.rejectAllPending(new Error('응답 크기가 너무 큽니다. 문서를 닫고 다시 열어주세요.'));
+                console.error(`[HWP MCP Bridge] Buffer exceeded ${this.MAX_BUFFER_SIZE / 1024 / 1024}MB — truncating oldest pending`);
+                // 버퍼를 비우되, 마지막 줄바꿈 이후 부분은 보존 (진행 중인 응답)
+                const lastNewline = this.buffer.lastIndexOf('\n');
+                this.buffer = lastNewline >= 0 ? this.buffer.slice(lastNewline + 1) : '';
+                // 가장 오래된 요청 하나만 거부
+                const oldestId = this.pending.keys().next().value;
+                if (oldestId) {
+                    const oldest = this.pending.get(oldestId);
+                    if (oldest) {
+                        clearTimeout(oldest.timer);
+                        oldest.reject(new Error('응답 크기가 너무 큽니다.'));
+                        this.pending.delete(oldestId);
+                    }
+                }
                 return;
             }
             this.processBuffer();
@@ -329,6 +340,9 @@ export class HwpBridge {
     getCurrentDocument() {
         return this.currentDocumentPath;
     }
+    getCurrentDocumentFormat() {
+        return this.currentDocumentFormat;
+    }
     getCachedAnalysis() {
         return this.lastAnalysis;
     }

package/dist/hwpx-engine.d.ts

@@ -24,9 +24,28 @@ export declare function extractTextFromSection(doc: Document): string[];
  * CLAUDE.md 규칙: 수정 후 linesegarray 삭제 필수.
  */
 export declare function replaceTextInSection(doc: Document, find: string, replace: string): number;
+/**
+ * HWPX section XML에서 텍스트 검색. COM FindReplace 우회용.
+ */
+export declare function searchTextInSection(doc: Document, searchText: string): {
+    total: number;
+    results: Array<{
+        index: number;
+        paragraph: number;
+        context: string;
+    }>;
+};
+/**
+ * HWPX section XML에서 N번째 텍스트만 치환.
+ */
+export declare function replaceTextNthInSection(doc: Document, find: string, replace: string, nth: number): boolean;
+/**
+ * HWPX section XML에서 텍스트를 찾아 그 뒤에 추가.
+ */
+export declare function findAndAppendInSection(doc: Document, find: string, appendText: string): boolean;
 /**
  * 빈 HWPX 파일 생성.
- * blank_template.hwpx를 복사하고, 필요시 제목 삽입.
+ * BUG-9 fix: blank_template.hwpx가 없으면 프로그래밍적으로 생성.
  */
 export declare function createBlankHwpx(outputPath: string, title?: string): Promise<void>;
 /**