claude-code-hwp-mcp 0.2.2 → 0.3.1

package/README.md

@@ -459,6 +459,102 @@ 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.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 호환
+
+---
+
 ## 지원 한글 버전
 
 한글 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();
@@ -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>;
 /**

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

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

package/dist/tools/analysis-tools.js

@@ -1,9 +1,11 @@
 /**
  * Analysis tools: analyze, get text, get tables, get fields
+ * HWPX 파일은 XML 직접 검색으로 라우팅 (COM 우회)
  */
 import { z } from 'zod';
 import path from 'node:path';
 import fs from 'node:fs';
+import { readHwpxXml, searchTextInSection } from '../hwpx-engine.js';
 const HWP_EXTENSIONS = new Set(['.hwp', '.hwpx']);
 const ANALYSIS_TIMEOUT = 60000;
 async function ensureAnalysis(bridge, filePath) {
@@ -141,10 +143,26 @@ export function registerAnalysisTools(server, bridge, toolset = 'standard') {
         search: z.string().describe('검색할 텍스트'),
         max_results: z.number().int().min(1).optional().describe('최대 검색 결과 수 (기본 50)'),
     }, async ({ search, max_results }) => {
-        if (!bridge.getCurrentDocument()) {
+        const filePath = bridge.getCurrentDocument();
+        if (!filePath) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: '열린 문서가 없습니다. hwp_open_document로 문서를 열어주세요.' }) }], isError: true };
         }
         try {
+            // HWPX → XML 직접 검색 시도. EBUSY 시 COM 폴백.
+            if (bridge.getCurrentDocumentFormat() === 'HWPX') {
+                try {
+                    const doc = await readHwpxXml(filePath, 'Contents/section0.xml');
+                    const result = searchTextInSection(doc, search);
+                    const limited = max_results ? result.results.slice(0, max_results) : result.results.slice(0, 50);
+                    return { content: [{ type: 'text', text: JSON.stringify({
+                                    search, total_found: result.total, results: limited, engine: 'xml',
+                                }) }] };
+                }
+                catch (xmlErr) {
+                    console.error('[text_search] XML failed, falling back to COM:', xmlErr.message);
+                }
+            }
+            // COM 경로 (HWP 또는 HWPX XML 실패 시 폴백)
             await bridge.ensureRunning();
             const params = { search };
             if (max_results)

package/dist/tools/editing-tools.js

@@ -1,8 +1,10 @@
 /**
  * Editing tools: fill fields, fill table cells, find/replace, insert text
+ * HWPX 파일은 XML 직접 조작으로 라우팅 (COM 우회)
  */
 import { z } from 'zod';
 import path from 'node:path';
+import { readHwpxXml, writeHwpxXml, replaceTextInSection, replaceTextNthInSection, findAndAppendInSection } from '../hwpx-engine.js';
 const FILL_TIMEOUT = 60000;
 export function registerEditingTools(server, bridge, toolset = 'standard') {
     // --- standard 이상에서만: fill_fields ---
@@ -121,13 +123,30 @@ export function registerEditingTools(server, bridge, toolset = 'standard') {
         replace: z.string().describe('바꿀 텍스트'),
         use_regex: z.boolean().optional().describe('정규식 사용 여부 (기본: false)'),
     }, async ({ find, replace, use_regex }) => {
-        if (!bridge.getCurrentDocument()) {
+        const filePath = bridge.getCurrentDocument();
+        if (!filePath) {
             return { content: [{ type: 'text', text: JSON.stringify({
                             error: '열린 문서가 없습니다. hwp_open_document로 문서를 열어주세요.',
-                            hint: 'Python 프로세스가 재시작되면 열린 문서 상태가 초기화됩니다.',
                         }) }], isError: true };
         }
         try {
+            // HWPX → XML 직접 치환 시도 (COM 우회). EBUSY 시 COM 폴백.
+            if (bridge.getCurrentDocumentFormat() === 'HWPX' && !use_regex) {
+                try {
+                    const doc = await readHwpxXml(filePath, 'Contents/section0.xml');
+                    const count = replaceTextInSection(doc, find, replace);
+                    await writeHwpxXml(filePath, filePath, 'Contents/section0.xml', doc);
+                    bridge.setCachedAnalysis(null);
+                    return { content: [{ type: 'text', text: JSON.stringify({
+                                    status: 'ok', find, replace, replaced: count > 0, count, engine: 'xml',
+                                }) }] };
+                }
+                catch (xmlErr) {
+                    // 파일 잠금(EBUSY) 등 XML 실패 시 COM 폴백
+                    console.error('[find_replace] XML failed, falling back to COM:', xmlErr.message);
+                }
+            }
+            // COM 경로 (HWP 또는 HWPX XML 실패 시 폴백)
             await bridge.ensureRunning();
             const params = { find, replace };
             if (use_regex)
@@ -152,12 +171,38 @@ export function registerEditingTools(server, bridge, toolset = 'standard') {
             })).describe('치환 목록'),
             use_regex: z.boolean().optional().describe('정규식 사용 여부 (기본: false)'),
         }, async ({ replacements, use_regex }) => {
-            if (!bridge.getCurrentDocument()) {
+            const filePath = bridge.getCurrentDocument();
+            if (!filePath) {
                 return { content: [{ type: 'text', text: JSON.stringify({
                                 error: '열린 문서가 없습니다. hwp_open_document로 문서를 열어주세요.',
                             }) }], isError: true };
             }
             try {
+                // HWPX → XML 직접 다건 치환 시도. EBUSY 시 COM 폴백.
+                if (bridge.getCurrentDocumentFormat() === 'HWPX' && !use_regex) {
+                    try {
+                        const doc = await readHwpxXml(filePath, 'Contents/section0.xml');
+                        const results = [];
+                        let totalCount = 0;
+                        for (const item of replacements) {
+                            const count = replaceTextInSection(doc, item.find, item.replace);
+                            results.push({ find: item.find, replaced: count > 0, count });
+                            totalCount += count;
+                        }
+                        if (totalCount > 0) {
+                            await writeHwpxXml(filePath, filePath, 'Contents/section0.xml', doc);
+                        }
+                        bridge.setCachedAnalysis(null);
+                        return { content: [{ type: 'text', text: JSON.stringify({
+                                        status: 'ok', results, total: results.length,
+                                        success: results.filter(r => r.replaced).length, engine: 'xml',
+                                    }) }] };
+                    }
+                    catch (xmlErr) {
+                        console.error('[find_replace_multi] XML failed, falling back to COM:', xmlErr.message);
+                    }
+                }
+                // COM 경로 (HWP 또는 HWPX XML 실패 시 폴백)
                 await bridge.ensureRunning();
                 const params = { replacements };
                 if (use_regex)
@@ -178,12 +223,30 @@ export function registerEditingTools(server, bridge, toolset = 'standard') {
             append_text: z.string().describe('찾은 텍스트 뒤에 추가할 텍스트'),
             color: z.array(z.number().int().min(0).max(255)).length(3).optional().describe('텍스트 색상 [R, G, B] (0-255)'),
         }, async ({ find, append_text, color }) => {
-            if (!bridge.getCurrentDocument()) {
+            const filePath = bridge.getCurrentDocument();
+            if (!filePath) {
                 return { content: [{ type: 'text', text: JSON.stringify({
                                 error: '열린 문서가 없습니다. hwp_open_document로 문서를 열어주세요.',
                             }) }], isError: true };
             }
             try {
+                // HWPX → XML 직접 조작 시도. EBUSY 시 COM 폴백.
+                if (bridge.getCurrentDocumentFormat() === 'HWPX' && !color) {
+                    try {
+                        const doc = await readHwpxXml(filePath, 'Contents/section0.xml');
+                        const found = findAndAppendInSection(doc, find, append_text);
+                        if (!found) {
+                            return { content: [{ type: 'text', text: JSON.stringify({ status: 'not_found', find, engine: 'xml' }) }] };
+                        }
+                        await writeHwpxXml(filePath, filePath, 'Contents/section0.xml', doc);
+                        bridge.setCachedAnalysis(null);
+                        return { content: [{ type: 'text', text: JSON.stringify({ status: 'ok', find, appended: true, engine: 'xml' }) }] };
+                    }
+                    catch (xmlErr) {
+                        console.error('[find_and_append] XML failed, falling back to COM:', xmlErr.message);
+                    }
+                }
+                // COM 경로 (HWP 또는 HWPX XML 실패 시 폴백)
                 await bridge.ensureRunning();
                 const params = { find, append_text };
                 if (color)
@@ -292,12 +355,31 @@ export function registerEditingTools(server, bridge, toolset = 'standard') {
             replace: z.string().describe('바꿀 텍스트'),
             nth: z.number().int().min(1).describe('몇 번째 매칭을 치환할지 (1부터 시작)'),
         }, async ({ find, replace, nth }) => {
-            if (!bridge.getCurrentDocument()) {
+            const filePath = bridge.getCurrentDocument();
+            if (!filePath) {
                 return { content: [{ type: 'text', text: JSON.stringify({
                                 error: '열린 문서가 없습니다. hwp_open_document로 문서를 열어주세요.',
                             }) }], isError: true };
             }
             try {
+                // HWPX → XML 직접 N번째 치환 시도. EBUSY 시 COM 폴백.
+                if (bridge.getCurrentDocumentFormat() === 'HWPX') {
+                    try {
+                        const doc = await readHwpxXml(filePath, 'Contents/section0.xml');
+                        const replaced = replaceTextNthInSection(doc, find, replace, nth);
+                        if (replaced) {
+                            await writeHwpxXml(filePath, filePath, 'Contents/section0.xml', doc);
+                        }
+                        bridge.setCachedAnalysis(null);
+                        return { content: [{ type: 'text', text: JSON.stringify({
+                                        status: 'ok', find, replace, nth, replaced, engine: 'xml',
+                                    }) }] };
+                    }
+                    catch (xmlErr) {
+                        console.error('[find_replace_nth] XML failed, falling back to COM:', xmlErr.message);
+                    }
+                }
+                // HWP → Python COM
                 await bridge.ensureRunning();
                 const response = await bridge.send('find_replace_nth', { find, replace, nth });
                 if (!response.success) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hwp-mcp",
-  "version": "0.2.2",
+  "version": "0.3.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",
@@ -14,7 +14,7 @@
   ],
   "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')}\"",
+    "postinstall": "node --input-type=commonjs -e \"try{require('child_process').execSync('python -c \\\"import pyhwpx\\\"',{stdio:'ignore'})}catch(e){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"

package/python/hwp_analyzer.py

@@ -91,8 +91,8 @@ def analyze_document(hwp, file_path, already_open=False):
     # 커서를 문서 처음으로 이동
     try:
         hwp.MovePos(2)  # movePOS_START: 문서 처음으로
-    except Exception:
-        pass
+    except Exception as e:
+        print(f"[WARN] MovePos failed: {e}", file=sys.stderr)
 
     result = {
         "file_path": file_path,
@@ -131,13 +131,16 @@ def analyze_document(hwp, file_path, already_open=False):
                     result["tables"].append(table_info)
                     try:
                         hwp.Cancel()
-                    except Exception:
-                        pass
+                    except Exception as e:
+                        print(f"[WARN] Cancel failed: {e}", file=sys.stderr)
                     table_idx += 1
                 except Exception:
                     break
+            # BUG-7 fix: 실제 발견된 표 수와 스캔 상한 분리
+            result["scanned_tables"] = table_idx
             if table_idx >= MAX_TABLES:
                 result["tables_truncated"] = True
+                result["tables_truncated_message"] = f"표가 {MAX_TABLES}개 이상일 수 있습니다. 처음 {MAX_TABLES}개만 분석했습니다."
                 print(f"[WARN] Table scan capped at {MAX_TABLES}", file=sys.stderr)
         except Exception as e:
             print(f"[WARN] Table extraction failed: {e}", file=sys.stderr)
@@ -152,8 +155,8 @@ def analyze_document(hwp, file_path, already_open=False):
                         value = ""
                         try:
                             value = hwp.GetFieldText(field.strip()) or ""
-                        except Exception:
-                            pass
+                        except Exception as e:
+                            print(f"[WARN] GetFieldText failed: {e}", file=sys.stderr)
                         result["fields"].append({
                             "name": field.strip(),
                             "value": value,
@@ -194,8 +197,8 @@ def analyze_document(hwp, file_path, already_open=False):
         if scan_started:
             try:
                 hwp.ReleaseScan()
-            except Exception:
-                pass
+            except Exception as e:
+                print(f"[WARN] ReleaseScan failed: {e}", file=sys.stderr)
 
     return result
 
@@ -235,8 +238,8 @@ def map_table_cells(hwp, table_idx, max_cells=200):
             finally:
                 try:
                     hwp.HAction.Run("Cancel")
-                except Exception:
-                    pass
+                except Exception as e:
+                    print(f"[WARN] Cancel in map_table_cells: {e}", file=sys.stderr)
 
             cell_map.append({
                 "tab": i,
@@ -251,8 +254,8 @@ def map_table_cells(hwp, table_idx, max_cells=200):
 
     try:
         hwp.Cancel()
-    except Exception:
-        pass
+    except Exception as e:
+        print(f"[WARN] Final cancel in map_table_cells: {e}", file=sys.stderr)
 
     return {
         "table_index": table_idx,

package/python/hwp_editor.py

@@ -28,8 +28,8 @@ def insert_text_with_color(hwp, text, rgb=None):
             act.GetDefault("CharShape", pset.HSet)
             pset.TextColor = hwp.RGBColor(0, 0, 0)
             act.Execute("CharShape", pset.HSet)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
 
 def insert_text_with_style(hwp, text, style=None):
@@ -102,24 +102,24 @@ def insert_text_with_style(hwp, text, style=None):
         try:
             pset.SpacingHangul = int(style["char_spacing"])
             pset.SpacingLatin = int(style["char_spacing"])
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "width_ratio" in style:
         try:
             pset.RatioHangul = int(style["width_ratio"])
             pset.RatioLatin = int(style["width_ratio"])
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "font_name_hanja" in style:
         try:
             pset.FaceNameHanja = style["font_name_hanja"]
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "font_name_japanese" in style:
         try:
             pset.FaceNameJapanese = style["font_name_japanese"]
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
     act.Execute("CharShape", pset.HSet)
 
@@ -137,14 +137,14 @@ def insert_text_with_style(hwp, text, style=None):
         try:
             pset.SpacingHangul = saved_char_spacing
             pset.SpacingLatin = saved_char_spacing
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if saved_width_ratio is not None:
         try:
             pset.RatioHangul = saved_width_ratio
             pset.RatioLatin = saved_width_ratio
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     act.Execute("CharShape", pset.HSet)
 
 
@@ -170,42 +170,42 @@ def set_paragraph_style(hwp, style=None):
     if "align" in style:
         try:
             pset.AlignType = align_map.get(style["align"], 0)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "line_spacing" in style:
         try:
             pset.LineSpacingType = style.get("line_spacing_type", 0)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         try:
             pset.LineSpacing = int(style["line_spacing"])
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "space_before" in style:
         try:
             pset.PrevSpacing = int(style["space_before"] * 100)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "space_after" in style:
         try:
             pset.NextSpacing = int(style["space_after"] * 100)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "indent" in style:
         try:
             pset.Indentation = int(style["indent"] * 100)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "left_margin" in style:
         try:
             pset.LeftMargin = int(style["left_margin"] * 100)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
     if "right_margin" in style:
         try:
             pset.RightMargin = int(style["right_margin"] * 100)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
     act.Execute("ParaShape", pset.HSet)
 
@@ -346,8 +346,8 @@ def get_cell_format(hwp, table_idx, cell_tab):
             hwp.HAction.Run("SelectAll")
             text_preview = hwp.GetTextFile("TEXT", "saveblock").strip()[:100]
             hwp.HAction.Run("Cancel")
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
         char = get_char_shape(hwp)
         para = get_para_shape(hwp)
@@ -362,8 +362,8 @@ def get_cell_format(hwp, table_idx, cell_tab):
     finally:
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
 
 def get_table_format_summary(hwp, table_idx, sample_tabs=None):
@@ -419,8 +419,8 @@ def _navigate_to_tab(hwp, table_idx, target_tab, current_tab):
     if moves < 0:
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         hwp.get_into_nth_table(table_idx)
         moves = target_tab
     for _ in range(moves):
@@ -477,8 +477,8 @@ def fill_table_cells_by_tab(hwp, table_idx, cells):
     finally:
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
     return result
 
@@ -530,8 +530,8 @@ def smart_fill_table_cells(hwp, table_idx, cells):
     finally:
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
     return result
 
@@ -539,17 +539,73 @@ def smart_fill_table_cells(hwp, table_idx, cells):
 def insert_markdown(hwp, md_text):
     """마크다운 텍스트를 한글 서식으로 변환하여 삽입.
 
-    지원: # 제목, **굵게**, *기울임*, - 목록, 일반 텍스트.
+    지원: # 제목, **굵게**, *기울임*, - 목록, | 표 |, > 인용, --- 구분선.
+    BUG-5 fix: 마크다운 표 파싱 추가.
     """
     import re
 
     lines = md_text.split('\n')
     inserted = 0
+    i = 0
+
+    while i < len(lines):
+        stripped = lines[i].strip()
 
-    for line in lines:
-        stripped = line.strip()
         if not stripped:
             hwp.insert_text('\r\n')
+            i += 1
+            continue
+
+        # 수평선 (---, ***, ___)
+        if re.match(r'^[-*_]{3,}$', stripped):
+            hwp.insert_text('─' * 40 + '\r\n')
+            inserted += 1
+            i += 1
+            continue
+
+        # 마크다운 표 (| 로 시작하는 연속된 줄)
+        if stripped.startswith('|') and '|' in stripped[1:]:
+            table_lines = []
+            while i < len(lines) and lines[i].strip().startswith('|'):
+                row_text = lines[i].strip()
+                # 구분선(|---|---|) 건너뛰기
+                if re.match(r'^\|[\s\-:]+\|', row_text):
+                    i += 1
+                    continue
+                # 셀 파싱
+                cells = [c.strip() for c in row_text.split('|')]
+                cells = [c for c in cells if c]  # 빈 문자열 제거
+                table_lines.append(cells)
+                i += 1
+            # 표 생성
+            if table_lines:
+                rows = len(table_lines)
+                cols = max(len(row) for row in table_lines)
+                hwp.create_table(rows, cols)
+                for r, row in enumerate(table_lines):
+                    for c in range(cols):
+                        val = row[c] if c < len(row) else ''
+                        if val:
+                            if r == 0:
+                                insert_text_with_style(hwp, val, {"bold": True})
+                            else:
+                                hwp.insert_text(val)
+                        if c < cols - 1 or r < rows - 1:
+                            hwp.TableRightCell()
+                try:
+                    hwp.Cancel()
+                except Exception:
+                    pass
+                hwp.insert_text('\r\n')
+                inserted += 1
+            continue
+
+        # 인용문 (>)
+        if stripped.startswith('>'):
+            quote_text = stripped.lstrip('>').strip()
+            hwp.insert_text('  │ ' + quote_text + '\r\n')
+            inserted += 1
+            i += 1
             continue
 
         # 제목 (# ~ ###)
@@ -557,30 +613,32 @@ def insert_markdown(hwp, md_text):
         if heading_match:
             level = len(heading_match.group(1))
             title_text = heading_match.group(2)
-            # 제목: Bold + 큰 글씨
             sizes = {1: 22, 2: 16, 3: 13}
             insert_text_with_style(hwp, title_text + '\r\n', {
                 "bold": True,
                 "font_size": sizes.get(level, 13),
             })
             inserted += 1
+            i += 1
             continue
 
-        # 목록 (- 또는 * 또는 숫자.)
+        # 목록 (- 또는 *)
         list_match = re.match(r'^[\-\*]\s+(.+)$', stripped)
         if list_match:
             hwp.insert_text('  ◦ ' + list_match.group(1) + '\r\n')
             inserted += 1
+            i += 1
             continue
 
+        # 번호 목록
         numbered_match = re.match(r'^(\d+)\.\s+(.+)$', stripped)
         if numbered_match:
             hwp.insert_text('  ' + numbered_match.group(1) + '. ' + numbered_match.group(2) + '\r\n')
             inserted += 1
+            i += 1
             continue
 
         # 인라인 서식 처리 (**굵게**, *기울임*)
-        # 간단 처리: **text** → text (bold로 삽입), 나머지 일반
         parts = re.split(r'(\*\*[^*]+\*\*|\*[^*]+\*)', stripped)
         for part in parts:
             if part.startswith('**') and part.endswith('**'):
@@ -591,6 +649,7 @@ def insert_markdown(hwp, md_text):
                 hwp.insert_text(part)
         hwp.insert_text('\r\n')
         inserted += 1
+        i += 1
 
     return {"status": "ok", "lines_inserted": inserted}
 
@@ -864,8 +923,8 @@ def set_cell_background_color(hwp, table_idx, cells):
     finally:
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
     return {"status": "ok", **result}
 
@@ -929,5 +988,5 @@ def set_table_border_style(hwp, table_idx, cells=None, style=None):
     finally:
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)

package/python/hwp_service.py

@@ -25,7 +25,13 @@ def validate_file_path(file_path, must_exist=True):
 
 
 def _execute_all_replace(hwp, find_str, replace_str, use_regex=False):
-    """AllReplace 공통 함수. find_replace/find_replace_multi/generate_multi에서 사용."""
+    """AllReplace 공통 함수. BUG-2 fix: COM 반환값 대신 전후 텍스트 비교로 검증."""
+    # 치환 전 텍스트 캡처
+    try:
+        before = hwp.get_text_file("TEXT", "")
+    except Exception:
+        before = ""
+
     act = hwp.HAction
     pset = hwp.HParameterSet.HFindReplace
     act.GetDefault("AllReplace", pset.HSet)
@@ -37,7 +43,14 @@ def _execute_all_replace(hwp, find_str, replace_str, use_regex=False):
     pset.FindJaso = 0
     pset.AllWordForms = 0
     pset.SeveralWords = 0
-    return bool(act.Execute("AllReplace", pset.HSet))
+    act.Execute("AllReplace", pset.HSet)
+
+    # 치환 후 텍스트 비교로 실제 변경 여부 판단
+    try:
+        after = hwp.get_text_file("TEXT", "")
+    except Exception:
+        after = ""
+    return before != after
 
 
 def respond(req_id, success, data=None, error=None):
@@ -98,8 +111,8 @@ def dispatch(hwp, method, params):
         # 파일 열기 전 다이얼로그 자동 처리 재확인
         try:
             hwp.XHwpMessageBoxMode = 1
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
 
         result = hwp.open(file_path)
         if not result:
@@ -116,8 +129,8 @@ def dispatch(hwp, method, params):
             result["pages"] = 0
         try:
             result["current_path"] = _current_doc_path or ""
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         return result
 
     if method == "analyze_document":
@@ -167,6 +180,11 @@ def dispatch(hwp, method, params):
         return {"status": "ok", "path": save_path, "file_size": file_size}
 
     if method == "close_document":
+        # BUG-8 fix: XHwpMessageBoxMode 복원
+        try:
+            hwp.XHwpMessageBoxMode = 0
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         hwp.close()
         _current_doc_path = None
         return {"status": "ok"}
@@ -184,15 +202,15 @@ def dispatch(hwp, method, params):
             pset.FindString = search_text
             pset.Direction = 0
             pset.IgnoreMessage = 1
-            found = act.Execute("FindReplace", pset.HSet)
-            if not found:
-                break
-            # 찾은 위치에서 컨텍스트 추출
+            act.Execute("FindReplace", pset.HSet)
+            # BUG-3 fix: 반환값 대신 선택 영역 존재 여부로 판단
             context = ""
             try:
                 context = hwp.GetTextFile("TEXT", "saveblock").strip()[:200]
             except Exception:
                 pass
+            if not context:
+                break  # 선택 영역이 없으면 더 이상 찾을 수 없음
             hwp.HAction.Run("Cancel")
             results.append({
                 "index": i + 1,
@@ -229,13 +247,18 @@ def dispatch(hwp, method, params):
         pset.FindString = params["find"]
         pset.Direction = 0
         pset.IgnoreMessage = 1
-        found = act.Execute("FindReplace", pset.HSet)
+        act.Execute("FindReplace", pset.HSet)
 
-        if not found:
+        # BUG-4 fix: 반환값 대신 선택 영역으로 찾기 성공 판단
+        try:
+            selected = hwp.GetTextFile("TEXT", "saveblock").strip()
+        except Exception:
+            selected = ""
+        if not selected:
             return {"status": "not_found", "find": params["find"]}
 
-        # 찾은 텍스트 끝으로 커서 이동 (선택 해제)
-        hwp.HAction.Run("Cancel")
+        # BUG-4 fix: Cancel 대신 MoveRight — 찾은 텍스트 끝으로 커서 이동
+        hwp.HAction.Run("MoveRight")
 
         # 색상 설정 (옵션)
         color = params.get("color")  # [r, g, b]
@@ -340,8 +363,8 @@ def dispatch(hwp, method, params):
         # BreakSection으로 페이지 분리 후 파일 삽입
         try:
             hwp.HAction.Run("BreakSection")
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         hwp.insert_file(merge_path)
         return {"status": "ok", "merged_file": merge_path, "pages": hwp.PageCount}
 
@@ -441,9 +464,8 @@ def dispatch(hwp, method, params):
         for r, row in enumerate(data):
             for c, val in enumerate(row):
                 if val:
-                    hwp.HAction.Run("SelectAll")
+                    # BUG-1 fix: SelectAll 제거 — 새 표의 빈 셀에 직접 삽입
                     if header_style and r == 0:
-                        # 헤더행: Bold + 가운데 정렬
                         from hwp_editor import insert_text_with_style
                         insert_text_with_style(hwp, str(val), {"bold": True})
                     else:
@@ -453,8 +475,8 @@ def dispatch(hwp, method, params):
                     hwp.TableRightCell()
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         # 헤더행 배경색 적용 (옵션)
         if header_style and rows > 0:
             try:
@@ -490,15 +512,15 @@ def dispatch(hwp, method, params):
         for r, row in enumerate(all_data):
             for c, val in enumerate(row):
                 if val:
-                    hwp.HAction.Run("SelectAll")
+                    # BUG-1 fix: SelectAll 제거
                     hwp.insert_text(str(val))
                     filled += 1
                 if c < len(row) - 1 or r < rows - 1:
                     hwp.TableRightCell()
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         return {"status": "ok", "file": os.path.basename(csv_path), "rows": rows, "cols": cols, "filled": filled}
 
     if method == "insert_heading":
@@ -710,9 +732,8 @@ def dispatch(hwp, method, params):
         for r, row in enumerate(data):
             for c, val in enumerate(row):
                 if val:
-                    hwp.HAction.Run("SelectAll")
+                    # BUG-1 fix: SelectAll 제거
                     if r == 0:
-                        # 헤더행: Bold
                         insert_text_with_style(hwp, str(val), {"bold": True})
                     else:
                         hwp.insert_text(str(val))
@@ -721,16 +742,16 @@ def dispatch(hwp, method, params):
                     hwp.TableRightCell()
         try:
             hwp.Cancel()
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         # 헤더행 + ■ 셀 배경색 적용
         try:
             from hwp_editor import set_cell_background_color
             style_cells = [{"tab": i, "color": "#D9D9D9"} for i in range(cols)]  # 헤더: 연회색
             style_cells += [{"tab": t, "color": "#C0C0C0"} for t in active_cells]  # ■셀: 음영
             set_cell_background_color(hwp, -1, style_cells)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         return {"status": "ok", "rows": rows, "cols": cols, "filled": filled, "active_cells": len(active_cells)}
 
     if method == "insert_date_code":
@@ -898,8 +919,8 @@ def dispatch(hwp, method, params):
                 count += 1
             hwp.ReleaseScan()
             text1 = "\n".join(parts)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         hwp.close()
         # 문서 2 텍스트 추출
         hwp.open(path2)
@@ -917,8 +938,8 @@ def dispatch(hwp, method, params):
                 count += 1
             hwp.ReleaseScan()
             text2 = "\n".join(parts)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         hwp.close()
         # diff 계산
         lines1 = text1.split("\n")
@@ -945,8 +966,8 @@ def dispatch(hwp, method, params):
                 count += 1
             hwp.ReleaseScan()
             text = "".join(parts)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         chars_total = len(text)
         chars_no_space = len(text.replace(" ", "").replace("\n", "").replace("\r", "").replace("\t", ""))
         words = len(text.split())
@@ -1046,8 +1067,8 @@ def dispatch(hwp, method, params):
                 count += 1
             hwp.ReleaseScan()
             text = "\n".join(parts)
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"[WARN] {e}", file=sys.stderr)
         # 패턴 감지: ( ), [ ], ___, ☐, □, ○, ◯, 빈칸+콜론
         patterns = [
             (r'\(\s*\)', 'bracket_empty', '빈 괄호'),