@kimdayoun/hwpx-mcp 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -5,6 +5,51 @@
 형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 를 따르고,
 버전은 [유의적 버전](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [0.3.5] - 2026-09-25
+
+0.3.4 의 ⑤ 수정이 MCP 도구 호출 경로에 닿지 않았던 것을 바로잡았습니다. 이번에는 회신 ①~⑥ 을
+단위·모듈·회귀·종단간 시험으로 모두 옮겼고, 버전 매트릭스에 0.3.4 를 넣었습니다.
+같은 시험 16개에서 0.3.0 은 3개, 0.3.3 은 7개, 0.3.4 는 13개, 이 버전은 16개를 통과합니다.
+
+### Fixed
+
+- **`update_paragraph_text` 로 글자 모양이 섞인 문단을 통째로 바꾸면 뒤쪽이 굵게 바뀌던
+  문제가 0.3.4 에서도 그대로였던 것.** 0.3.4 는 문서 쪽 함수를 고쳤지만, 도구는 run 이 둘
+  이상인 문단을 받으면 그 함수를 부르지 않고 글을 원래 run 들에 나눠 담는 쪽으로 넘겼습니다.
+  신고와 같은 호출로 재면 0.3.3 과 0.3.4 모두 새 글 35자가 굵은 run 에 들어갔고, 한/글 2024
+  화면에서 셋째 줄 가운데부터 굵게 보였습니다. 이제 run 0 교체는 늘 문단 전체를 첫 run 의
+  글자 모양 하나로 씁니다. run 마다 글자 모양을 지키려면 `update_paragraph_text_preserve_styles`
+  를 씁니다. 한/글 2020 이 저장한 원본의 첫 섞인 문단에서 0.3.3 은 83건 중 3건, 0.3.4 는 4건,
+  이 버전은 82건 중 82건이 제대로 바뀌었습니다.
+- **문단을 통째로 바꿔도 앞 공백·탭 뒤 글이 남거나, 문단이 사라지던 문제.** 한/글은 글 하나를
+  고정폭 빈칸·탭 앞뒤로 여러 조각으로 읽는데, 첫 조각만 바꿨습니다. 보도자료 본문 문단은
+  0.3.4 에서 저장 뒤 빈 줄만 남았습니다. 이제 문단의 자기 글 자리에 새 글을 쓰고 나머지 조각을
+  비웁니다. 표·글상자·수식·그림·각주는 그대로 둡니다.
+- **글상자를 품은 문단이 글상자 글로 읽히고, 고치면 성공이라 답하면서 글상자 밖에 쓰던 문제.**
+  문단을 읽을 때 run 을 문단 전체에서 찾아, 글상자 속 문단의 `</hp:run>` 에서 run 이 끝났습니다.
+  그래서 "[글상자] 자기 글" 문단은 글상자 글로 읽혔고, 고치면 새 글이 글상자 옆에 따로 찍혔으며
+  (한/글 2024 에서 확인), 다시 열면 옛 글상자 글이 나왔습니다. 이제 문단은 글상자·머리말·표 같은
+  중첩 내용을 뺀 자기 글로 읽습니다. 글상자 안 글은 따로 올라오는 속 문단으로 고치면 글상자 안에
+  들어갑니다. 한/글 원본 275건에서 자기 글이 읽을 때 빠지던 문단이 41개에서 1개(HWP 5 변환본의
+  옛 한글 자모)로 줄었고, 중첩 내용을 품은 문단을 통째로 바꾸고 다시 열었을 때 새 글이 안 보이던
+  경우가 72건 중 18건에서 0건이 됐습니다. 머리말을 품은 첫 문단도 이제 본문 글로 읽혀, 고쳐도
+  머리말 글이 그대로입니다.
+- **문단을 통째로 바꾼 뒤 같은 문단의 다른 조각을 고치면 그 글이 저장본에서 빠지던 문제.**
+  탭이 든 문단에서 run 0 을 바꾸고 run 2 를 고치면 메모리는 두 글을 다 가졌지만 저장본에는
+  run 0 글만 남았습니다(0.3.4 는 run 0 글까지 빠졌습니다). 이제 호출한 순서대로 합쳐 씁니다.
+- **글상자 속 문단과 그 글상자를 품은 문단을 한 번에 고치면 바깥 문단 쓰기가 빠지던 문제.**
+  속 문단 글이 길어지면 바깥 문단이 끝나는 위치를 잘못 잡아, 성공이라 답하고 옛 글을 남겼습니다.
+  이제 문단마다 쓰기 직전에 끝 위치를 다시 잽니다.
+
+한/글 원본 200건에서 문단 통째 교체를 재면, 파서가 읽은 글과 문단 자기 글이 같은 문단은
+0.3.4 가 144건 중 135건, 이 버전이 144건 모두 제자리에 들어갔습니다. 둘이 다른 문단 12건은
+0.3.4 가 모두 어긋났고, 이 버전은 12건 모두 제자리에 들어갔습니다.
+
+### 알려진 제한
+
+- 표 칸 글 쓰기에서, 칸 안에 문단이 여럿이거나 그림만 있는 칸은 글이 원래 자리에 들어가지
+  않을 수 있습니다(한/글 원본 209건 중 67건, 0.3.3 과 같음).
+
 ## [0.3.4] - 2026-09-24
 
 0.3.3 을 실제 업무 양식·실문서에 쓴 2차 사용 회신(6건)을 재현해 고쳤습니다.
@@ -47,8 +92,10 @@
   병합하거나 1열 표를 세로로 병합하면 저장본에 칸이 하나도 없는 행이 생겼고, 한/글 2024 는
   이 파일에서 PDF 를 만들지 못했습니다. 한/글 원본 275건에는 칸 없는 행이 한 건도 없습니다.
   이제 이런 병합은 어느 행이 비는지 알려 주고 거부합니다. 0.3.3 에도 있던 문제입니다.
-- **글자 모양이 섞인 문단을 통째로 바꾸면 뒤쪽이 굵게 바뀌던 문제.** run 0 을 바꾸면
-  첫 run 의 글자 모양으로 문단 전체를 씁니다.
+- **글자 모양이 섞인 문단을 통째로 바꾸면 뒤쪽이 굵게 바뀌던 문제.** 문서 쪽 `updateParagraphText`
+  는 run 0 을 바꾸면 첫 run 의 글자 모양으로 문단 전체를 쓰도록 고쳤습니다. 다만 MCP 도구
+  `update_paragraph_text` 는 이 함수를 거치지 않아 0.3.4 에서도 증상이 남았고, 0.3.5 에서
+  고쳤습니다.
 - **실패한 호출도 `isError: false` 로 오던 문제.**
 
 ### 알려진 제한

package/README.md

@@ -309,11 +309,11 @@ npm run test:module         # 모듈: 문서 API → 저장 → 다시 열기로
 npm run test:regression     # 회귀: 신고 1건당 파일 1개, 신고 문장을 주석으로 붙임
 npm run test:e2e            # 종단간: 빌드한 MCP 서버를 stdio 로 띄워 호출
 npm run test:security       # 빌드 후 실제 MCP 저장 경로 공격·반복 저장·실패 정리 검사
-npm run test:versions -- 0.3.3 local   # 같은 e2e 를 게시된 버전과 로컬 빌드에 돌려 표로 비교
+npm run test:versions -- 0.3.4 local   # 같은 e2e 를 게시된 버전과 로컬 빌드에 돌려 표로 비교
 ```
 
 e2e 는 `HWPX_MCP_SERVER` 로 대상 서버를 고릅니다. `local`(기본)은 이 저장소의
-`dist/index.js`, `npm:0.3.3` 은 게시된 버전입니다. `local` 서버를 띄울 Node 는
+`dist/index.js`, `npm:0.3.4` 는 게시된 버전입니다. `local` 서버를 띄울 Node 는
 `HWPX_MCP_NODE` 로 바꿉니다(CI 는 Node 18·22 로 돌립니다).
 
 문단 저장 회귀 테스트는 개인 PC의 문서 경로 대신 합성 HWPX를 사용합니다.

package/dist/HwpxDocument.d.ts

@@ -1277,6 +1277,22 @@ export declare class HwpxDocument {
      * Returns the paragraph's start, end, and XML content in the original document.
      */
     private findTargetParagraphForUpdate;
+    /**
+     * Replace the whole own text of a paragraph (run 0 of updateParagraphText).
+     *
+     * The new text goes into the paragraph's first own text node — the first
+     * <hp:t> with text, outside every nested container — and every other own
+     * text node is emptied, including characters written as elements inside
+     * them (tab, full-width space, line break). The first run's character shape
+     * therefore carries the whole sentence. Nested content (tables, text boxes,
+     * equations, pictures, notes) and all attributes stay byte-for-byte.
+     *
+     * Written by position rather than memory run index: the parser splits one
+     * <hp:t> into several memory runs around tabs and full-width spaces, so run 0
+     * named only a fragment and the rest of the old text survived (measured
+     * 2026-09-25 on 150 Hancom originals: 449 of 11,754 paragraphs).
+     */
+    private replaceWholeParagraphText;
     /**
      * Replace multiple runs in a paragraph element at once.
      * Finds hp:run elements and updates their hp:t content.

package/dist/HwpxDocument.js

@@ -564,35 +564,36 @@ class HwpxDocument {
         // Track for XML update - always add if we have a zip (HWPX file)
         // Similar to updateTableCell which always tracks changes
         if (this._zip) {
-            const oldText = paragraph.runs[runIndex].text || '';
             const paragraphOccurrence = this.getParagraphOccurrence(sectionIndex, elementIndex, paragraph.id || '');
-            this._pendingDirectTextUpdates.push({
-                sectionIndex,
-                elementIndex,
-                paragraphId: paragraph.id || '', // Use stable paragraph ID for reliable identification
-                paragraphOccurrence,
-                paragraph,
-                runIndex,
-                oldText,
-                newText: text
-            });
-            // When updating run 0, clear other runs (full paragraph replacement)
             if (runIndex === 0) {
-                for (let i = 1; i < paragraph.runs.length; i++) {
-                    const otherOldText = paragraph.runs[i].text || '';
-                    if (otherOldText) {
-                        this._pendingDirectTextUpdates.push({
-                            sectionIndex,
-                            elementIndex,
-                            paragraphId: paragraph.id || '',
-                            paragraphOccurrence,
-                            paragraph,
-                            runIndex: i,
-                            oldText: otherOldText,
-                            newText: '' // Clear other runs
-                        });
-                    }
-                }
+                // Whole-paragraph replacement is written by position (see
+                // wholeParagraph): the new text goes into the paragraph's first own
+                // text node and its other own text nodes are emptied. A paragraph that
+                // holds a text box reads as its own text only; the box's text is the
+                // next element, so editing it writes inside the box.
+                this._pendingDirectTextUpdates.push({
+                    sectionIndex,
+                    elementIndex,
+                    paragraphId: paragraph.id || '',
+                    paragraphOccurrence,
+                    paragraph,
+                    runIndex: 0,
+                    oldText: paragraph.runs.map(r => r.text || '').join(''),
+                    newText: text,
+                    wholeParagraph: true,
+                });
+            }
+            else {
+                this._pendingDirectTextUpdates.push({
+                    sectionIndex,
+                    elementIndex,
+                    paragraphId: paragraph.id || '', // Use stable paragraph ID for reliable identification
+                    paragraphOccurrence,
+                    paragraph,
+                    runIndex,
+                    oldText: paragraph.runs[runIndex].text || '',
+                    newText: text
+                });
             }
         }
         this.saveState();
@@ -6804,9 +6805,40 @@ class HwpxDocument {
             });
             // STEP 3: Apply updates using pre-computed positions
             for (const [elementIndex, updates] of sortedEntries) {
-                const target = paragraphTargets.get(elementIndex);
-                if (!target)
+                const found = paragraphTargets.get(elementIndex);
+                if (!found)
                     continue;
+                // Writes go bottom-to-top, so a start computed before them still names
+                // this paragraph. Its end may not: the parser lifts a text-box paragraph
+                // out as its own element, so the box's paragraph and the paragraph that
+                // holds the box overlap, and the inner one (later start) is written first.
+                // If that changed length, the pre-computed end fell inside the outer
+                // paragraph and its write was dropped (CodeRabbit, PR #17). Re-measure.
+                const end = this.findBalancedParagraphEnd(xml, found.start);
+                if (end === -1)
+                    continue;
+                const target = { start: found.start, end, xml: xml.slice(found.start, end) };
+                // A whole-paragraph replacement (run 0 of updateParagraphText) is
+                // written by position and replaces every earlier edit of this
+                // paragraph. Run edits made after it are folded into its text, not
+                // applied as a second pass: after a whole replacement the XML has one
+                // text node while memory can still hold several runs (the parser split
+                // "A<hp:tab/>B" into ["A", "", "B"]), so run N no longer names an XML
+                // node and a second pass dropped the edit (CodeRabbit, PR #17).
+                // Updates are in call order here (the list is filled in call order).
+                const lastWhole = updates.map(u => !!u.wholeParagraph).lastIndexOf(true);
+                if (lastWhole !== -1) {
+                    const runTexts = [updates[lastWhole].newText];
+                    for (const u of updates.slice(lastWhole + 1)) {
+                        // Memory after the replacement: run 0 holds the new text, runs
+                        // 1.. are empty until edited; an edit sets that run's text.
+                        runTexts[u.runIndex] = u.newText;
+                    }
+                    const text = Array.from(runTexts, t => t ?? '').join('');
+                    const current = { start: target.start, end: target.end, xml: xml.slice(target.start, target.end) };
+                    xml = this.replaceWholeParagraphText(xml, current, text);
+                    continue;
+                }
                 // Sort by runIndex to process in order
                 updates.sort((a, b) => a.runIndex - b.runIndex);
                 // Apply the update directly using pre-computed target location
@@ -7495,6 +7527,55 @@ class HwpxDocument {
         // Final fallback: return index-based result anyway
         return indexBasedTarget;
     }
+    /**
+     * Replace the whole own text of a paragraph (run 0 of updateParagraphText).
+     *
+     * The new text goes into the paragraph's first own text node — the first
+     * <hp:t> with text, outside every nested container — and every other own
+     * text node is emptied, including characters written as elements inside
+     * them (tab, full-width space, line break). The first run's character shape
+     * therefore carries the whole sentence. Nested content (tables, text boxes,
+     * equations, pictures, notes) and all attributes stay byte-for-byte.
+     *
+     * Written by position rather than memory run index: the parser splits one
+     * <hp:t> into several memory runs around tabs and full-width spaces, so run 0
+     * named only a fragment and the rest of the old text survived (measured
+     * 2026-09-25 on 150 Hancom originals: 449 of 11,754 paragraphs).
+     */
+    replaceWholeParagraphText(xml, target, newText) {
+        let paragraphXml = target.xml;
+        const escaped = this.escapeXml(newText);
+        const runs = this.findDirectChildRuns(paragraphXml);
+        // Own text nodes of each run, as (run, has non-empty own text).
+        const hasText = (runXml) => [...this.ownRunText(runXml).matchAll(/<hp:t\b[^>]*>([\s\S]*?)<\/hp:t>/g)]
+            .some(m => /<hp:(?:tab|fwSpace|nbSpace|lineBreak)\b/.test(m[1]) || m[1].replace(/<[^>]+>/g, '') !== '');
+        let firstIdx = runs.findIndex(r => hasText(r.xml));
+        // No own text anywhere: fall back to the first own <hp:t> (empty paragraph).
+        if (firstIdx === -1)
+            firstIdx = runs.findIndex(r => /<hp:t\b/.test(this.ownRunText(r.xml)));
+        for (let i = runs.length - 1; i >= 0; i--) {
+            const run = runs[i];
+            let written = i !== firstIdx; // only the first chosen run receives the text
+            const newRunXml = this.mapOwnRunText(run.xml, part => part.replace(/<hp:t\b([^>]*?)\/>|<hp:t\b([^>]*)>([\s\S]*?)<\/hp:t>/g, (_m, selfAttrs, attrs) => {
+                const text = written ? '' : escaped;
+                written = true;
+                return `<hp:t${selfAttrs ?? attrs ?? ''}>${text}</hp:t>`;
+            }));
+            paragraphXml = paragraphXml.slice(0, run.start) + newRunXml + paragraphXml.slice(run.end);
+        }
+        if (firstIdx === -1) {
+            // The paragraph has no <hp:t> of its own: add one to its first run.
+            const firstRun = runs[0];
+            if (firstRun) {
+                const openEnd = firstRun.xml.indexOf('>') + 1;
+                const withText = firstRun.xml.endsWith('/>')
+                    ? firstRun.xml.replace(/\/>$/, `><hp:t>${escaped}</hp:t></hp:run>`)
+                    : firstRun.xml.slice(0, openEnd) + `<hp:t>${escaped}</hp:t>` + firstRun.xml.slice(openEnd);
+                paragraphXml = paragraphXml.slice(0, firstRun.start) + withText + paragraphXml.slice(firstRun.end);
+            }
+        }
+        return xml.slice(0, target.start) + paragraphXml + xml.slice(target.end);
+    }
     /**
      * Replace multiple runs in a paragraph element at once.
      * Finds hp:run elements and updates their hp:t content.

package/dist/HwpxParser.d.ts

@@ -31,6 +31,19 @@ export declare class HwpxParser {
     private static parseColumnDef;
     private static parseImageEffects;
     private static parseParagraphsSimple;
+    /**
+     * The paragraph with every nested container (table, text box, drawing
+     * object, header/footer, caption, equation, note…) cut out, leaving only its
+     * own runs and text. Section paragraphs are read from this: the paragraphs
+     * inside those containers are listed as elements of their own, and the save
+     * path writes a paragraph's text into exactly these own <hp:t>
+     * (HwpxDocument.ownRunText). Reading the whole paragraph instead ended its
+     * run at the first nested </hp:run>: a paragraph "[text box] own text" read
+     * as the text box's text, its own text was never seen, and a whole-paragraph
+     * edit reopened as the old text box text (CodeRabbit, PR #17; 41 of 16,733
+     * paragraphs with own text in 275 Hancom originals lost it on reading).
+     */
+    private static withoutNestedContent;
     private static parseParagraph;
     private static parseRun;
     private static processTextContent;

package/dist/HwpxParser.js

@@ -1283,7 +1283,9 @@ class HwpxParser {
         elements.sort((a, b) => a.index - b.index);
         for (const el of elements) {
             if (el.type === 'p') {
-                const paragraph = this.parseParagraph(el.xml);
+                // Own content only: the paragraphs inside its text boxes, headers and
+                // captions are elements of their own (withoutNestedContent).
+                const paragraph = this.parseParagraph(this.withoutNestedContent(el.xml));
                 // Store XML position from original XML for direct updates
                 // This enables fast paragraph updates without re-parsing during save()
                 if (el.originalXmlPosition) {
@@ -1864,6 +1866,53 @@ class HwpxParser {
         }
         return paragraphs;
     }
+    /**
+     * The paragraph with every nested container (table, text box, drawing
+     * object, header/footer, caption, equation, note…) cut out, leaving only its
+     * own runs and text. Section paragraphs are read from this: the paragraphs
+     * inside those containers are listed as elements of their own, and the save
+     * path writes a paragraph's text into exactly these own <hp:t>
+     * (HwpxDocument.ownRunText). Reading the whole paragraph instead ended its
+     * run at the first nested </hp:run>: a paragraph "[text box] own text" read
+     * as the text box's text, its own text was never seen, and a whole-paragraph
+     * edit reopened as the old text box text (CodeRabbit, PR #17; 41 of 16,733
+     * paragraphs with own text in 275 Hancom originals lost it on reading).
+     */
+    static withoutNestedContent(paragraphXml) {
+        const nested = /<hp:(tbl|subList|equation|pic|rect|ellipse|polygon|curve|arc|line|container|drawText|textart|ole|footNote|endNote|header|footer)\b/;
+        const openEnd = paragraphXml.indexOf('>') + 1;
+        let rest = paragraphXml.slice(openEnd);
+        let own = '';
+        for (;;) {
+            const m = rest.match(nested);
+            if (!m || m.index === undefined) {
+                own += rest;
+                break;
+            }
+            own += rest.slice(0, m.index);
+            const re = new RegExp(`<(/?)hp:${m[1]}\\b[^>]*?(/?)>`, 'g');
+            re.lastIndex = m.index;
+            let depth = 0;
+            let end = rest.length;
+            let t;
+            while ((t = re.exec(rest)) !== null) {
+                if (t[2]) {
+                    if (depth === 0) {
+                        end = t.index + t[0].length;
+                        break;
+                    }
+                    continue;
+                }
+                depth += t[1] ? -1 : 1;
+                if (depth === 0) {
+                    end = t.index + t[0].length;
+                    break;
+                }
+            }
+            rest = rest.slice(end);
+        }
+        return paragraphXml.slice(0, openEnd) + own;
+    }
     static parseParagraph(xml) {
         // Extract only the opening <hp:p ...> tag to get paragraph attributes
         const pTagMatch = xml.match(/^<hp:p\s+([^>]*)>/);

package/dist/ToolResult.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP tool-result envelope and argument checks, kept out of index.ts so they
+ * can be tested without starting the stdio server.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare function success(data: unknown): CallToolResult;
+export declare function error(message: string): CallToolResult;
+/**
+ * The declared-required arguments of `toolName` that `args` leaves undefined or
+ * null. Reporting them by name replaced a generic handler failure: omitting
+ * `section_index` used to surface as "Failed to insert paragraph", which reads
+ * like document corruption.
+ */
+export declare function findMissingArgs(requiredByTool: ReadonlyMap<string, readonly string[]>, toolName: string, args: Record<string, unknown> | undefined): string[];

package/dist/ToolResult.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.success = success;
+exports.error = error;
+exports.findMissingArgs = findMissingArgs;
+function success(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function error(message) {
+    // isError tells the MCP client the call failed. Without it, a missing
+    // argument or a refused write came back as a normal result whose body merely
+    // contained {"error": …}, and agents treated it as success (reported
+    // 2026-09-24). The JSON body is kept for clients that read it.
+    return { content: [{ type: 'text', text: JSON.stringify({ error: message }) }], isError: true };
+}
+/**
+ * The declared-required arguments of `toolName` that `args` leaves undefined or
+ * null. Reporting them by name replaced a generic handler failure: omitting
+ * `section_index` used to surface as "Failed to insert paragraph", which reads
+ * like document corruption.
+ */
+function findMissingArgs(requiredByTool, toolName, args) {
+    const required = requiredByTool.get(toolName);
+    if (!required || required.length === 0)
+        return [];
+    return required.filter(key => args?.[key] === undefined || args?.[key] === null);
+}