@kimdayoun/hwpx-mcp 0.3.0 → 0.3.3

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/index.js

@@ -41,8 +41,7 @@ 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 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 +104,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 +146,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)' },
             },
@@ -1894,12 +1898,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 +2134,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 +2142,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 +2320,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 +2361,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 {
@@ -2400,31 +2449,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 +4043,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 ===

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.3",
   "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,6 +50,7 @@
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "test": "vitest run",
+    "test:security": "npm run build && node --test test-save-security.mjs",
     "test:watch": "vitest"
   },
   "dependencies": {