@kimdayoun/hwpx-mcp 0.3.0 → 0.3.4

package/dist/HwpxParser.js

@@ -1883,7 +1883,10 @@ class HwpxParser {
         // Get paragraph shape reference from the <hp:p> tag
         const paraShapeRefMatch = pTagAttrs.match(/paraPrIDRef="(\d+)"/);
         if (paraShapeRefMatch) {
-            const paraShape = this.styles.paraShapes.get(parseInt(paraShapeRefMatch[1]));
+            // Keep the raw reference: callers assembling XML by hand need the numeric
+            // ID, and resolving it to style values throws the ID away.
+            paragraph.paraPrId = parseInt(paraShapeRefMatch[1]);
+            const paraShape = this.styles.paraShapes.get(paragraph.paraPrId);
             if (paraShape) {
                 paragraph.paraStyle = {
                     align: paraShape.align,
@@ -1943,8 +1946,9 @@ class HwpxParser {
         const runs = [];
         let charStyle;
         const charShapeRefMatch = xml.match(/charPrIDRef="(\d+)"/);
+        const charPrIDRef = charShapeRefMatch ? parseInt(charShapeRefMatch[1]) : undefined;
         if (charShapeRefMatch) {
-            const charShape = this.styles.charShapes.get(parseInt(charShapeRefMatch[1]));
+            const charShape = this.styles.charShapes.get(charPrIDRef);
             if (charShape) {
                 charStyle = {
                     fontName: charShape.fontName,
@@ -2113,6 +2117,15 @@ class HwpxParser {
                 charStyle: { ...charStyle, superscript: true, fontSize: charStyle?.fontSize ? charStyle.fontSize * 0.7 : 7 },
             });
         }
+        // Attach the raw header.xml reference to every run produced here. Callers
+        // that assemble XML directly need this ID; resolving it into style values
+        // alone forces them back to regex-scraping section0.xml.
+        if (charPrIDRef !== undefined) {
+            for (const run of runs) {
+                if (run.charPrIDRef === undefined)
+                    run.charPrIDRef = charPrIDRef;
+            }
+        }
         return runs;
     }
     static processTextContent(tContent, charStyle, runs, hyperlink, field) {
@@ -3106,6 +3119,9 @@ class HwpxParser {
                         type: 'hr',
                         data: {
                             id: generateId(),
+                            // The paragraph stays in the XML; keep its id so id-based
+                            // anchors can count it (HwpxDocument.resolveElementAnchor).
+                            sourceParagraphId: el.data.id,
                             width: 'full',
                             height: 1,
                             color: '#000000',

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,8 +41,8 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const HwpxDocument_1 = require("./HwpxDocument");
 const HangingIndentCalculator_1 = require("./HangingIndentCalculator");
-// Version marker for debugging
-const MCP_VERSION = 'v2-fixed-xml-replacement';
+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
 const openDocuments = new Map();
@@ -105,11 +105,16 @@ Example: get_tool_guide({ workflow: "template" })`,
             properties: {
                 workflow: {
                     type: 'string',
-                    description: 'Workflow type: template, table, image, search, read, create, or all',
+                    description: 'Workflow type: template, table, image, search, read, create, or all. Also accepted as topic.',
+                    enum: ['template', 'table', 'image', 'search', 'read', 'create', 'all']
+                },
+                topic: {
+                    type: 'string',
+                    description: 'Alias for workflow.',
                     enum: ['template', 'table', 'image', 'search', 'read', 'create', 'all']
                 },
             },
-            required: ['workflow'],
+            anyOf: [{ required: ['workflow'] }, { required: ['topic'] }],
         },
     },
     // === Document Management ===
@@ -142,7 +147,7 @@ Example: get_tool_guide({ workflow: "template" })`,
             type: 'object',
             properties: {
                 doc_id: { type: 'string', description: 'Document ID' },
-                output_path: { type: 'string', description: 'Output path (optional, saves to original if omitted)' },
+                output_path: { type: 'string', description: 'Absolute or relative output path. Required for documents from create_document that were not given a file_path. Also accepted as file_path.' },
                 create_backup: { type: 'boolean', description: 'Create .bak backup before saving (default: true)' },
                 verify_integrity: { type: 'boolean', description: 'Verify saved file integrity (default: true)' },
             },
@@ -630,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
@@ -1894,12 +1905,13 @@ Positioning within cell:
     // === New Document Creation ===
     {
         name: 'create_document',
-        description: 'Create a new empty HWPX document',
+        description: 'Create a new empty HWPX document. Pass file_path to fix where save_document will write it; otherwise you must pass output_path to save_document.',
         inputSchema: {
             type: 'object',
             properties: {
                 title: { type: 'string', description: 'Document title (optional)' },
                 creator: { type: 'string', description: 'Document author (optional)' },
+                file_path: { type: 'string', description: 'Destination path for later saves (optional). The file is written on save_document, not here.' },
             },
         },
     },
@@ -2129,7 +2141,7 @@ Call this after modifying the document to ensure fresh data on next read operati
 // ============================================================
 const server = new index_js_1.Server({
     name: 'hwpx-mcp-server',
-    version: '0.3.0',
+    version: MCP_VERSION,
 }, {
     capabilities: {
         tools: {},
@@ -2137,15 +2149,40 @@ const server = new index_js_1.Server({
 });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools }));
 // ============================================================
+// Required-argument validation
+// ============================================================
+const requiredArgsByTool = new Map(tools.map(tool => [
+    tool.name,
+    (tool.inputSchema?.required) ?? [],
+]));
+/**
+ * Report the exact missing arguments instead of letting the handler fail with a
+ * generic message. `section_index` is declared required on the insert/update
+ * tools, but omitting it used to surface as "Failed to insert paragraph", which
+ * reads like document corruption and sends callers off inspecting the file.
+ */
+function findMissingArgs(toolName, args) {
+    const required = requiredArgsByTool.get(toolName);
+    if (!required || required.length === 0)
+        return [];
+    return required.filter(key => args?.[key] === undefined || args?.[key] === null);
+}
+// ============================================================
 // Tool Handlers
 // ============================================================
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    const missing = findMissingArgs(name, args);
+    if (missing.length > 0) {
+        return error(`Missing required argument${missing.length > 1 ? 's' : ''} for ${name}: ${missing.join(', ')}`);
+    }
     try {
         switch (name) {
             // === 🎯 Tool Guide ===
             case 'get_tool_guide': {
-                const workflow = args?.workflow;
+                // `topic` is the name callers reach for first; accept both rather than
+                // silently returning the same full reference for every request.
+                const workflow = args?.workflow ?? args?.topic;
                 const guides = {
                     template: `📋 TEMPLATE/FORM WORKFLOW (양식 작업)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -2290,8 +2327,12 @@ For best results, start with a template file instead.`,
 💡 WORKFLOW GUIDES:
 Call get_tool_guide with: template, table, image, search, read, create`
                 };
-                const guide = guides[workflow] || guides['all'];
-                return success({ workflow, guide });
+                const known = Object.keys(guides);
+                const guide = guides[workflow];
+                if (!guide) {
+                    return error(`Unknown workflow "${workflow}". Available: ${known.join(', ')}`);
+                }
+                return success({ workflow, available_workflows: known, guide });
             }
             // === Document Management ===
             case 'open_document': {
@@ -2327,25 +2368,40 @@ Call get_tool_guide with: template, table, image, search, read, create`
                     return error('HWP files are read-only');
                 // Use document lock to ensure all pending updates complete before save
                 return await withDocumentLock(docId, async () => {
-                    const savePath = args?.output_path || doc.path;
+                    // `file_path` is the parameter name used by open_document/create_document,
+                    // so callers reach for it here too. Accept it rather than silently
+                    // falling back to the document's own path.
+                    const requestedPath = args?.output_path || args?.file_path;
+                    if (!requestedPath && !doc.hasPath) {
+                        return error('output_path is required for a document created with create_document; ' +
+                            'it has no location on disk yet');
+                    }
+                    const savePath = path.resolve(requestedPath || doc.path);
                     const createBackup = args?.create_backup !== false; // default: true
                     const verifyIntegrity = args?.verify_integrity !== false; // default: true
                     let backupPath = null;
-                    const tempPath = savePath + '.tmp';
-                    // Create backup if file exists and backup is enabled
-                    if (createBackup && fs.existsSync(savePath)) {
-                        backupPath = savePath + '.bak';
-                        try {
-                            fs.copyFileSync(savePath, backupPath);
-                        }
-                        catch (backupErr) {
-                            return error(`Failed to create backup: ${backupErr}`);
-                        }
+                    const saveDirectory = path.dirname(savePath);
+                    if (!fs.existsSync(saveDirectory)) {
+                        return error(`Directory does not exist: ${saveDirectory}`);
                     }
+                    // A private directory prevents pre-created .tmp symlinks from redirecting writes.
+                    const tempDirectory = fs.mkdtempSync(path.join(saveDirectory, '.hwpx-save-'));
+                    const tempPath = path.join(tempDirectory, 'document.hwpx');
                     try {
+                        if (createBackup && fs.existsSync(savePath)) {
+                            backupPath = savePath + '.bak';
+                            const existingBackup = fs.lstatSync(backupPath, { throwIfNoEntry: false });
+                            if (existingBackup && !existingBackup.isFile()) {
+                                return error('Backup destination must be a regular file');
+                            }
+                            const stagedBackup = path.join(tempDirectory, 'backup.hwpx');
+                            fs.copyFileSync(savePath, stagedBackup, fs.constants.COPYFILE_EXCL);
+                            // Rename replaces the directory entry instead of following a destination symlink.
+                            fs.renameSync(stagedBackup, backupPath);
+                        }
                         const data = await doc.save();
                         // Phase 1: Write to temp file first (atomic write pattern)
-                        fs.writeFileSync(tempPath, data);
+                        fs.writeFileSync(tempPath, data, { flag: 'wx', mode: 0o600 });
                         // Verify integrity on temp file before moving
                         if (verifyIntegrity) {
                             try {
@@ -2368,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) {
@@ -2400,31 +2445,22 @@ Call get_tool_guide with: template, table, image, search, read, create`
                                 return error(`Save verification failed: ${verifyErr}`);
                             }
                         }
-                        // Phase 2: Atomic move - rename temp to final (atomic on same filesystem)
-                        if (fs.existsSync(savePath)) {
-                            fs.unlinkSync(savePath);
-                        }
+                        // Do not unlink first: a failed rename must leave the original document intact.
                         fs.renameSync(tempPath, savePath);
+                        doc.setPath(savePath);
                         return success({
                             message: `Saved to ${savePath}`,
+                            path: savePath,
                             backup_created: backupPath ? true : false,
+                            backup_path: backupPath,
                             integrity_verified: verifyIntegrity
                         });
                     }
                     catch (saveErr) {
-                        // Clean up temp file if exists
-                        if (fs.existsSync(tempPath)) {
-                            try {
-                                fs.unlinkSync(tempPath);
-                            }
-                            catch { }
-                        }
-                        // Restore from backup if save fails
-                        if (backupPath && fs.existsSync(backupPath)) {
-                            fs.copyFileSync(backupPath, savePath);
-                            return error(`Save failed, restored from backup: ${saveErr}`);
-                        }
-                        return error(`Save failed: ${saveErr}`);
+                        return error(`Save failed; original document preserved: ${saveErr}`);
+                    }
+                    finally {
+                        fs.rmSync(tempDirectory, { recursive: true, force: true });
                     }
                 });
             }
@@ -4003,11 +4039,26 @@ Call get_tool_guide with: template, table, image, search, read, create`
             case 'create_document': {
                 const docId = generateId();
                 const doc = HwpxDocument_1.HwpxDocument.createNew(docId, args?.title, args?.creator);
+                // Remember the intended destination so a later save_document without an
+                // explicit path writes where the caller asked, not into the server cwd.
+                const requestedPath = args?.file_path || args?.output_path;
+                let plannedPath = null;
+                if (requestedPath) {
+                    plannedPath = path.resolve(requestedPath);
+                    const parentDirectory = path.dirname(plannedPath);
+                    if (!fs.existsSync(parentDirectory)) {
+                        return error(`Directory does not exist: ${parentDirectory}`);
+                    }
+                    doc.setPath(plannedPath);
+                }
                 openDocuments.set(docId, doc);
                 return success({
                     doc_id: docId,
                     format: 'hwpx',
-                    message: 'New document created',
+                    path: plannedPath,
+                    message: plannedPath
+                        ? `New document created; save_document will write to ${plannedPath}`
+                        : 'New document created; pass output_path to save_document to choose where it is written',
                 });
             }
             // === XML Analysis and Repair ===
@@ -4297,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/dist/types.d.ts

@@ -997,6 +997,11 @@ export interface HwpxTextBox {
 }
 export interface HwpxHorizontalRule {
     id: string;
+    /**
+     * Id of the <hp:p> this rule was parsed from. The paragraph is still in the
+     * section XML, so id-based insert anchors must count it.
+     */
+    sourceParagraphId?: string;
     width: number | 'full';
     height: number;
     color?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kimdayoun/hwpx-mcp",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "description": "한글 문서(HWPX)를 읽고 쓰는 MCP 서버 — 125개 도구. 문단·표·스타일·이미지·머리말/꼬리말까지 XML 수준으로 편집한다. MCP Server for Korean HWPX documents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -49,13 +50,20 @@
     "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"
   },
   "dependencies": {
     "@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",