@kimdayoun/hwpx-mcp 0.3.3 → 0.3.4

package/dist/XmlWellFormed.d.ts

@@ -0,0 +1,5 @@
+import type JSZip from 'jszip';
+/** First well-formedness error in `xml`, or null when it parses. */
+export declare function xmlWellFormednessError(xml: string): string | null;
+/** Every `.xml` / `.hpf` part of the package that does not parse, as "path: error". */
+export declare function findMalformedXmlParts(zip: JSZip): Promise<string[]>;

package/dist/XmlWellFormed.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.xmlWellFormednessError = xmlWellFormednessError;
+exports.findMalformedXmlParts = findMalformedXmlParts;
+/**
+ * Well-formedness check for the XML parts of a saved HWPX package.
+ *
+ * save_document(verify_integrity) used to look for three textual symptoms
+ * (no `<?xml`, a dangling `<` at the end, `<` inside a tag). A section with a
+ * mismatched close tag passed all three and was reported as
+ * `integrity_verified: true`, while Hancom and every XML parser rejected it
+ * (reported 2026-09-24: `<hp:p>` 5730 open / 5728 close after one edit).
+ * A real parser is the only check that means what the flag claims.
+ *
+ * Measured on 275 Hancom-saved originals (2,046 XML parts, 168 MB): 0 false
+ * rejections, ~1.5 s total. The only rejected sample was a password-protected
+ * file, whose parts are ciphertext rather than XML.
+ */
+const saxes_1 = require("saxes");
+/** First well-formedness error in `xml`, or null when it parses. */
+function xmlWellFormednessError(xml) {
+    // xmlns: true also rejects an undeclared prefix (<hs:sec> with only
+    // xmlns:hp declared). Hancom declares every prefix it uses (0 rejections
+    // across the 275-file corpus with this setting), while set_section_xml
+    // accepted a section missing xmlns:hs.
+    const parser = new saxes_1.SaxesParser({ xmlns: true });
+    let first = null;
+    parser.on('error', err => {
+        if (first === null)
+            first = err.message;
+    });
+    try {
+        parser.write(xml).close();
+    }
+    catch (err) {
+        first ?? (first = err instanceof Error ? err.message : String(err));
+    }
+    return first;
+}
+/** Every `.xml` / `.hpf` part of the package that does not parse, as "path: error". */
+async function findMalformedXmlParts(zip) {
+    const out = [];
+    const names = Object.keys(zip.files)
+        .filter(name => !zip.files[name].dir && /\.(xml|hpf)$/i.test(name))
+        .sort();
+    for (const name of names) {
+        const err = xmlWellFormednessError(await zip.file(name).async('string'));
+        if (err)
+            out.push(`${name}: ${err}`);
+    }
+    return out;
+}

package/dist/index.js

@@ -41,6 +41,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const HwpxDocument_1 = require("./HwpxDocument");
 const HangingIndentCalculator_1 = require("./HangingIndentCalculator");
+const XmlWellFormed_1 = require("./XmlWellFormed");
 const MCP_VERSION = require('../package.json').version;
 console.error(`[HWPX MCP] Server starting - ${MCP_VERSION} - ${new Date().toISOString()}`);
 // Document storage
@@ -634,14 +635,20 @@ When NOT to use:
         description: `⭐ RECOMMENDED for finding tables. Returns ALL tables with their headers and metadata.
 
 Returns for each table:
-- table_index: Global index (use this for other table operations)
+- section_index + table_index_in_section: pass BOTH to tools that take section_index
+  (update_table_cell, get_table_cell, get_table, insert_table_row, insert_table_column,
+  merge_cells, insert_nested_table, …)
+- table_index: position across the whole document. ONLY for tools that take no
+  section_index (get_cell_context, batch_fill_table, insert_image_in_cell,
+  render_mermaid_in_cell, insert_paragraph after_table)
 - header: Text from the paragraph BEFORE the table (usually the table title)
 - size: rows × cols
 - is_empty: Whether table has content
 - first_row_preview: Preview of first row data
 
-Use this FIRST when working with tables, then use the table_index for:
-- get_table, update_table_cell, insert_image_in_cell, etc.
+In a document with one section both indices are equal. With a cover section plus
+a body section they differ: passing table_index to update_table_cell writes to a
+DIFFERENT table (or fails) — use table_index_in_section there.
 
 Alternative tools:
 - find_table_by_header: Search by header text
@@ -2417,24 +2424,13 @@ Call get_tool_guide with: template, table, image, search, read, create`
                                 if (missingFiles.length > 0) {
                                     throw new Error(`Missing required files: ${missingFiles.join(', ')}`);
                                 }
-                                // Verify all section XML files are valid
-                                const sectionFiles = Object.keys(zip.files).filter(f => f.match(/^Contents\/section\d+\.xml$/));
-                                for (const sectionFile of sectionFiles) {
-                                    const file = zip.file(sectionFile);
-                                    if (file) {
-                                        const xmlContent = await file.async('string');
-                                        if (!xmlContent || !xmlContent.includes('<?xml')) {
-                                            throw new Error(`Invalid XML in ${sectionFile}`);
-                                        }
-                                        // Check for truncated XML (incomplete tag at end)
-                                        if (xmlContent.match(/<[^>]*$/)) {
-                                            throw new Error(`Truncated XML in ${sectionFile}`);
-                                        }
-                                        // Check for broken opening tags (< followed by < without >)
-                                        if (xmlContent.match(/<[^>]*</)) {
-                                            throw new Error(`Broken tag structure in ${sectionFile}`);
-                                        }
-                                    }
+                                // Every XML part must actually parse. The old textual checks
+                                // (<?xml present, no dangling '<') passed a section with a
+                                // mismatched close tag, and the save reported
+                                // integrity_verified: true for a file Hancom cannot open.
+                                const malformed = await (0, XmlWellFormed_1.findMalformedXmlParts)(zip);
+                                if (malformed.length > 0) {
+                                    throw new Error(`Malformed XML: ${malformed.slice(0, 3).join('; ')}`);
                                 }
                             }
                             catch (verifyErr) {
@@ -4352,7 +4348,11 @@ function success(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
 function error(message) {
-    return { content: [{ type: 'text', text: JSON.stringify({ 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 };
 }
 function escapeHtml(text) {
     return text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kimdayoun/hwpx-mcp",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "한글 문서(HWPX)를 읽고 쓰는 MCP 서버 — 125개 도구. 문단·표·스타일·이미지·머리말/꼬리말까지 XML 수준으로 편집한다. MCP Server for Korean HWPX documents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,6 +50,11 @@
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "test": "vitest run",
+    "test:unit": "vitest run src tests/unit",
+    "test:module": "vitest run tests/module",
+    "test:regression": "vitest run tests/regression",
+    "test:e2e": "npm run build && vitest run tests/e2e",
+    "test:versions": "node scripts/version-matrix.mjs",
     "test:security": "npm run build && node --test test-save-security.mjs",
     "test:watch": "vitest"
   },
@@ -57,7 +62,8 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "hwp.js": "^0.0.3",
     "jszip": "^3.10.1",
-    "pako": "^2.1.0"
+    "pako": "^2.1.0",
+    "saxes": "^6.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",