claude-code-hwp-mcp 0.2.2 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Claude Code와 Claude Desktop에서 한글(HWP) 문서를 AI로 자동 편집하는 MCP 서버입니다.
 
-85개 이상의 도구로 문서 열기, 표 채우기, 텍스트 편집, 서식 설정, PDF 변환까지 모두 자동화할 수 있습니다.
+94개 도구로 문서 열기, 표 채우기, 텍스트 편집, 서식 설정, 페이지 레이아웃, PDF 시각 검증까지 모두 자동화할 수 있습니다.
 
 > Windows 전용 | 한글 2014 이상 | Python 3.8+ | Claude Code + Claude Desktop 지원
 
@@ -299,7 +299,7 @@ Python 경로, pyhwpx 설치 여부, 한글 프로그램 설치 및 실행 상
 
 ---
 
-## 기능 목록 (85개+)
+## 기능 목록 (94개)
 
 ### 환경/문서 관리 (6개)
 
@@ -379,16 +379,30 @@ Python 경로, pyhwpx 설치 여부, 한글 프로그램 설치 및 실행 상
 | hwp_set_cell_color | 셀 배경색 설정 |
 | hwp_set_table_border | 표 테두리 스타일 설정 |
 
-### 이미지/레이아웃 (5개)
+### 페이지/레이아웃 (9개)
 
 | 도구 | 설명 |
 |------|------|
+| hwp_set_page_setup | 여백, 용지 크기, 방향(가로/세로) 설정 |
+| hwp_set_header_footer | 머리글/바닥글 삽입 |
+| hwp_set_column | 다단 설정 (2단/3단, 구분선) |
+| hwp_verify_layout | PDF→PNG 시각 검증 (PyMuPDF) |
 | hwp_insert_picture | 이미지 삽입 |
 | hwp_set_background_picture | 배경 이미지 설정 |
 | hwp_insert_line | 선(줄) 삽입 |
 | hwp_break_section | 섹션 나누기 |
 | hwp_break_column | 다단 나누기 |
 
+### 서식/그리기 (5개)
+
+| 도구 | 설명 |
+|------|------|
+| hwp_apply_style | 문단 스타일 적용 ("제목1", "본문" 등) |
+| hwp_set_cell_property | 셀 여백/수직정렬/텍스트방향/보호 |
+| hwp_insert_textbox | 글상자 생성 (위치/크기 지정) |
+| hwp_draw_line | 선 그리기 (두께/색상/스타일) |
+| hwp_insert_caption | 표/그림 캡션 삽입 |
+
 ### 스마트/복합 도구 (16개)
 
 | 도구 | 설명 |
@@ -459,6 +473,130 @@ Python Bridge (hwp_service.py + pyhwpx)
 
 ---
 
+## HWP vs HWPX 파일 형식 차이
+
+| 구분 | 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 → 저장
+```
+
+### 텍스트 치환
+
+```
+1. hwp_open_document → 파일 열기
+2. hwp_find_replace 또는 hwp_find_replace_multi → 치환
+3. hwp_save_document → 저장
+```
+
+### 문서 분석
+
+```
+1. hwp_open_document → 파일 열기
+2. hwp_analyze_document → 전체 구조 분석
+3. hwp_get_tables → 표 데이터 확인
+4. hwp_word_count → 글자수 통계
+```
+
+---
+
+## 변경 이력
+
+### v0.5.0 (2026-03-25) — 94개 도구, 표 서식 대폭 강화
+
+**신규 도구 9개:**
+- `hwp_set_page_setup` — 여백, 용지 크기, 방향(가로/세로) 설정
+- `hwp_set_header_footer` — 머리글/바닥글 삽입 (CreateAction 방식, 대화상자 없음)
+- `hwp_set_column` — 다단 설정 (2단/3단, 구분선)
+- `hwp_verify_layout` — PDF→PNG 시각 검증 (PyMuPDF 필요)
+- `hwp_apply_style` — 문단 스타일 적용 ("제목1", "본문" 등)
+- `hwp_set_cell_property` — 셀 여백/수직정렬/텍스트방향/보호
+- `hwp_insert_textbox` — 글상자 생성 (위치/크기 지정)
+- `hwp_draw_line` — 선 그리기 (두께/색상/스타일)
+- `hwp_insert_caption` — 표/그림 캡션 삽입
+
+**텍스트 서식 속성 25+ 추가 (insert_text):**
+- 밑줄: underline_type(7종), underline_color
+- 취소선: strikeout_type(4종), strikeout_color
+- 효과: superscript, subscript, outline, shadow, emboss, engrave, small_caps
+- 글꼴: font_name_latin(라틴 전용), shadow_color, use_kerning
+- 배경: bg_color
+
+**문단 서식 속성 11개 추가 (set_paragraph_style):**
+- page_break_before, keep_with_next, widow_orphan
+- line_wrap, snap_to_grid, auto_space_eAsian_eng/num
+- break_latin_word, heading_type, keep_lines_together, condense
+
+**표 기능 핵심 개선:**
+- 셀 배경색: pyhwpx `cell_fill()` 내장 메서드 사용 (안정적)
+- 셀 텍스트 정렬: `TableCellAlignCenterCenter` 액션 사용 (삽입 후 적용)
+- 셀 병합: `TableCellBlockExtend` 방식으로 정확한 블록 선택
+- 표 생성: col_widths(mm), row_heights(mm), alignment(left/center/right), header_style(Bold)
+- 테두리: color(#RRGGBB), edges(방향별 적용) 지원
+
+**버그 수정:**
+- insert_text 자동 줄바꿈 — 각 호출이 독립 문단으로 생성
+- set_header_footer: `CreateAction("HeaderFooter")` 방식 (대화상자 타임아웃 해결)
+- apply_style: `Execute("Style")` + `SetItem("StyleName")` (대화상자 방지)
+- draw_line: 대화형 InsertLine fallback 제거
+- insert_footnote/endnote: try/except + CloseEx 추가
+- get_cursor_context: page → total_pages + current_page(KeyIndicator)
+
+### v0.3.0 — HWPX XML 라우팅 + 10건 버그 수정
+
+**버그 수정 (10건):**
+- SelectAll 문서 파괴 수정 (table_create_from_data, gantt_chart 등)
+- find_replace 전후 텍스트 비교 검증으로 개선
+- text_search 선택 영역 기반 판단으로 개선
+- find_and_append 커서 유실 수정 (Cancel → MoveRight)
+- 버퍼 오버플로우 시 개별 요청만 거부
+- XHwpMessageBoxMode 복원 (close_document)
+- blank_template.hwpx 프로그래밍적 생성 (파일 의존성 제거)
+
+**HWPX XML 라우팅:**
+- HWPX 파일의 텍스트 검색/치환을 Node.js XML 엔진으로 직접 처리
+- XML 실패 시(파일 잠금 등) COM 경로로 자동 폴백
+
+**환경 진단 개선:**
+- Microsoft Store Python 자동 감지 + 경고
+- 한글 프로세스 실행 여부 체크 (tasklist)
+
+---
+
 ## 지원 한글 버전
 
 한글 2014, 2018, 2020, 2022, 2024 모두 지원합니다.

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();
@@ -278,23 +289,28 @@ export class HwpBridge {
             };
             return result;
         }
-        // 3) 한글(HWP) COM 등록 체크
+        // 3) 한글(HWP) 설치 체크 — COM Dispatch 대신 파일 존재 + pyhwpx import 확인
+        // (COM Dispatch는 빈 한글 문서를 열어버리는 부작용이 있으므로 제거)
         try {
-            await execFileAsync(pythonExe, ['-c', 'import win32com.client; o = win32com.client.gencache.EnsureDispatch("HWPFrame.HwpObject"); o.XHwpDocuments.Close(False); del o'], { timeout: 15000 });
-            result.hwp = { found: true };
-        }
-        catch (err) {
-            const msg = err.message || '';
-            if (msg.includes('COM class not registered') || msg.includes('gencache')) {
-                result.hwp = {
-                    found: false,
-                    guide: '한글(HWP) 프로그램이 설치되지 않았습니다.\n→ 한컴오피스 한글 설치 필요 (한글 2014 이상)\n→ 설치 후 한글을 한번 실행하여 초기 설정 완료',
-                };
+            const { stdout } = await execFileAsync(pythonExe, ['-c',
+                'import os; paths = [r"C:\\Program Files\\Hancom", r"C:\\Program Files (x86)\\Hancom"]; ' +
+                    'found = any(os.path.isdir(p) for p in paths); ' +
+                    'print("installed" if found else "not_found")'
+            ], { timeout: 5000 });
+            if (stdout.trim() === 'installed') {
+                result.hwp = { found: true };
             }
             else {
-                result.hwp = { found: true };
+                // 폴더가 없어도 pyhwpx가 COM을 찾을 수 있으므로 pyhwpx import 성공이면 OK
+                result.hwp = { found: true, guide: '한컴 설치 폴더를 찾을 수 없지만, pyhwpx가 설치되어 있으므로 동작할 수 있습니다.' };
             }
         }
+        catch {
+            result.hwp = {
+                found: false,
+                guide: '한글(HWP) 프로그램이 설치되지 않았습니다.\n→ 한컴오피스 한글 설치 필요 (한글 2014 이상)\n→ 설치 후 한글을 한번 실행하여 초기 설정 완료',
+            };
+        }
         // 4) 한글 프로세스 실행 여부 체크
         try {
             const { stdout } = await execFileAsync('tasklist', ['/FI', 'IMAGENAME eq Hwp.exe', '/NH'], { timeout: 5000 });
@@ -329,6 +345,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>;
 /**

package/dist/hwpx-engine.js

@@ -114,6 +114,77 @@ export function replaceTextInSection(doc, find, replace) {
     }
     return count;
 }
+// ── HWPX XML 검색 (COM 우회) ──
+/**
+ * HWPX section XML에서 텍스트 검색. COM FindReplace 우회용.
+ */
+export function searchTextInSection(doc, searchText) {
+    const results = [];
+    const paragraphs = doc.getElementsByTagNameNS(NS_HP, 'p');
+    let matchCount = 0;
+    for (let i = 0; i < paragraphs.length; i++) {
+        const runs = paragraphs[i].getElementsByTagNameNS(NS_HP, 'run');
+        let paraText = '';
+        for (let j = 0; j < runs.length; j++) {
+            const tNodes = runs[j].getElementsByTagNameNS(NS_HP, 't');
+            for (let k = 0; k < tNodes.length; k++) {
+                paraText += tNodes[k].textContent || '';
+            }
+        }
+        let pos = 0;
+        while ((pos = paraText.indexOf(searchText, pos)) !== -1) {
+            matchCount++;
+            const start = Math.max(0, pos - 20);
+            const end = Math.min(paraText.length, pos + searchText.length + 20);
+            results.push({
+                index: matchCount,
+                paragraph: i,
+                context: paraText.slice(start, end),
+            });
+            pos += searchText.length;
+        }
+    }
+    return { total: matchCount, results };
+}
+/**
+ * HWPX section XML에서 N번째 텍스트만 치환.
+ */
+export function replaceTextNthInSection(doc, find, replace, nth) {
+    const tNodes = doc.getElementsByTagNameNS(NS_HP, 't');
+    let matchCount = 0;
+    for (let i = 0; i < tNodes.length; i++) {
+        const t = tNodes[i];
+        const text = t.textContent || '';
+        let pos = 0;
+        while ((pos = text.indexOf(find, pos)) !== -1) {
+            matchCount++;
+            if (matchCount === nth) {
+                t.textContent = text.slice(0, pos) + replace + text.slice(pos + find.length);
+                removeLinesegarray(doc);
+                return true;
+            }
+            pos += find.length;
+        }
+    }
+    return false;
+}
+/**
+ * HWPX section XML에서 텍스트를 찾아 그 뒤에 추가.
+ */
+export function findAndAppendInSection(doc, find, appendText) {
+    const tNodes = doc.getElementsByTagNameNS(NS_HP, 't');
+    for (let i = 0; i < tNodes.length; i++) {
+        const t = tNodes[i];
+        const text = t.textContent || '';
+        const pos = text.indexOf(find);
+        if (pos !== -1) {
+            t.textContent = text.slice(0, pos + find.length) + appendText + text.slice(pos + find.length);
+            removeLinesegarray(doc);
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * linesegarray 요소 삭제 (CLAUDE.md 규칙 8).
  */
@@ -128,19 +199,55 @@ function removeLinesegarray(doc) {
     }
 }
 // ── 빈 HWPX 생성 ──
+/**
+ * BUG-9 fix: blank_template.hwpx 파일 의존 제거.
+ * 최소 유효 HWPX를 프로그래밍적으로 생성.
+ */
+async function createMinimalHwpx(outputPath, title) {
+    const zip = new JSZip();
+    // mimetype
+    zip.file('mimetype', 'application/hwp+zip');
+    // META-INF/manifest.xml
+    zip.file('META-INF/manifest.xml', `<?xml version="1.0" encoding="UTF-8"?>
+<manifest:manifest xmlns:manifest="urn:oasis:names:tc:opendocument:xmlns:manifest:1.0">
+  <manifest:file-entry manifest:full-path="/" manifest:media-type="application/hwp+zip"/>
+  <manifest:file-entry manifest:full-path="Contents/section0.xml" manifest:media-type="text/xml"/>
+  <manifest:file-entry manifest:full-path="Contents/content.hpf" manifest:media-type="text/xml"/>
+</manifest:manifest>`);
+    // Contents/content.hpf
+    zip.file('Contents/content.hpf', `<?xml version="1.0" encoding="UTF-8"?>
+<hp:HWPMLPackageFormat xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph">
+  <hp:BodyText>
+    <hp:SectionRef hp:IDRef="0"/>
+  </hp:BodyText>
+</hp:HWPMLPackageFormat>`);
+    // Contents/section0.xml
+    const titleText = title || '';
+    zip.file('Contents/section0.xml', `<?xml version="1.0" encoding="UTF-8"?>
+<hp:sec xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph">
+  <hp:p>
+    <hp:run>
+      <hp:t>${titleText}</hp:t>
+    </hp:run>
+  </hp:p>
+</hp:sec>`);
+    const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+    fs.writeFileSync(outputPath, buffer);
+}
 function getTemplatePath() {
-    // ESM에서 __dirname 대안
     const thisFile = new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1');
     return path.join(path.dirname(thisFile), '../../blank_template.hwpx');
 }
 /**
  * 빈 HWPX 파일 생성.
- * blank_template.hwpx를 복사하고, 필요시 제목 삽입.
+ * BUG-9 fix: blank_template.hwpx가 없으면 프로그래밍적으로 생성.
  */
 export async function createBlankHwpx(outputPath, title) {
     const templatePath = getTemplatePath();
     if (!fs.existsSync(templatePath)) {
-        throw new Error(`빈 HWPX 템플릿을 찾을 수 없습니다: ${templatePath}. 한글에서 빈 문서를 HWPX로 저장하세요.`);
+        // 템플릿 파일 없음 → 프로그래밍적 생성
+        await createMinimalHwpx(outputPath, title);
+        return;
     }
     fs.copyFileSync(templatePath, outputPath);
     if (title) {

package/dist/index.js

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