mcp-word-bridge 3.5.1 → 3.5.3

package/README.md

@@ -80,7 +80,7 @@ mcp-word-bridge/
 └── README.md
 ```
 
-## Tools (91)
+## Tools (92)
 
 ### Document
 | Tool | Description |
@@ -107,6 +107,7 @@ mcp-word-bridge/
 | `word_delete_paragraph` | Delete a paragraph by index |
 | `word_replace_paragraph_text` | Replace paragraph text by index (preserves style) |
 | `word_move_paragraph` | Move one or more consecutive paragraphs to another position |
+| `word_copy_paragraph` | Copy one or more consecutive paragraphs to another position |
 | `word_set_paragraph_style` | Change style or alignment of a paragraph |
 | `word_set_paragraph_spacing` | Set line spacing, before/after, and indentation |
 

package/index.js

@@ -62,12 +62,18 @@ const sslOptions = {
   cert: fs.readFileSync(path.join(CERTS_DIR, 'cert.pem'))
 };
 
-const MIME = { '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css', '.png': 'image/png', '.json': 'application/json' };
+const MIME = { '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css', '.png': 'image/png', '.json': 'application/json', '.xml': 'application/xml' };
 
 const httpsServer = https.createServer(sslOptions, (req, res) => {
   let urlPath = req.url.split('?')[0];
   let filePath = urlPath === '/' ? '/taskpane.html' : urlPath;
-  filePath = path.join(__dirname, filePath);
+  filePath = path.resolve(__dirname, '.' + filePath);
+  // Prevent path traversal — resolved path must stay within __dirname
+  if (!filePath.startsWith(__dirname + path.sep) && filePath !== __dirname) {
+    res.writeHead(403);
+    res.end('Forbidden');
+    return;
+  }
   const ext = path.extname(filePath);
   const contentType = MIME[ext] || 'application/octet-stream';
   fs.readFile(filePath, (err, data) => {
@@ -88,7 +94,7 @@ const httpsServer = https.createServer(sslOptions, (req, res) => {
 });
 
 // WebSocket relay: taskpane ↔ bridge (MCP server)
-const wss = new WebSocketServer({ server: httpsServer });
+const wss = new WebSocketServer({ server: httpsServer, maxPayload: 10 * 1024 * 1024 });
 let taskpaneSocket = null;
 const bridgePending = new Map();
 
@@ -105,7 +111,15 @@ wss.on('connection', (ws, req) => {
         }
       } catch (_e) {}
     });
-    ws.on('close', () => { process.stderr.write('[bridge] Taskpane disconnected\n'); taskpaneSocket = null; });
+    ws.on('close', () => {
+      process.stderr.write('[bridge] Taskpane disconnected\n');
+      taskpaneSocket = null;
+      // Reject all pending operations immediately instead of waiting for timeout
+      for (const [_id, pending] of bridgePending) {
+        pending.reject(new Error('Word taskpane disconnected. Reopen the MCP Word Bridge add-in in Word.'));
+      }
+      bridgePending.clear();
+    });
   }
   // The /bridge endpoint is no longer needed — MCP server calls sendToTaskpane directly
 });
@@ -134,7 +148,7 @@ function sendToTaskpane(action, params) {
 }
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.5.1' },
+  { name: 'mcp-word-bridge', version: '3.5.3' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -163,16 +177,19 @@ async function executeTool(name, args) {
       await sendToTaskpane('insertOoxml', { ooxml, location: args.location || 'End' });
     } else if (args.anchorText) {
       // Inline mode with anchor: search for anchor text, insert space+marker after it, insert equation at cursor, clean up marker
-      const marker = '\u200B\uFEFF'; // unique two-char sequence unlikely to exist in normal text
+      const marker = '\u200B\uFEFF\u200B'; // three-char zero-width sequence — virtually impossible in real documents
       const searchResult = await sendToTaskpane('search', { query: args.anchorText, matchCase: args.matchCase || false });
       if (!searchResult || searchResult.count === 0) throw new Error('Anchor not found: ' + args.anchorText);
       const occurrence = args.occurrence || 0;
       if (occurrence >= searchResult.count) throw new Error('Occurrence ' + occurrence + ' not found (only ' + searchResult.count + ' match' + (searchResult.count === 1 ? '' : 'es') + ')');
       // Insert space + marker to position cursor (space ensures equation doesn't glue to preceding text)
       await sendToTaskpane('insertText', { text: ' ' + marker, after: args.anchorText, occurrence: occurrence, matchCase: args.matchCase || false });
-      await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
-      // Clean up the marker (space remains, giving proper separation)
-      await sendToTaskpane('searchAndReplace', { find: marker, replace: '' });
+      try {
+        await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
+      } finally {
+        // Always clean up the marker, even if equation insertion fails
+        await sendToTaskpane('searchAndReplace', { find: marker, replace: '' });
+      }
     } else {
       await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
     }
@@ -185,18 +202,25 @@ async function executeTool(name, args) {
     const result = await sendToTaskpane('getParagraphs', {});
     const headings = [];
     for (const para of result.paragraphs) {
+      // Skip TOC entries — they duplicate real headings
+      if (para.isTocEntry) continue;
+      let level = null;
+      // Primary: match style name "Heading N"
       const match = para.style && para.style.match(/^Heading (\d)$/i);
       if (match) {
-        const level = parseInt(match[1], 10);
-        if (level <= maxLevel) {
-          headings.push({ level, text: para.text, index: para.index });
-        }
+        level = parseInt(match[1], 10);
+      } else if (para.outlineLevel !== undefined && para.outlineLevel >= 1 && para.outlineLevel <= 9) {
+        // Fallback: use outlineLevel when style is empty or unrecognized (e.g. after TOC insertion)
+        level = para.outlineLevel;
+      }
+      if (level !== null && level <= maxLevel) {
+        headings.push({ level, text: para.text, index: para.index });
       }
     }
     return { content: [{ type: 'text', text: JSON.stringify({ count: headings.length, outline: headings }, null, 2) }] };
   }
 
-  // word_move_paragraph: atomic move (read text+style, delete, insert at new position)
+  // word_move_paragraph: OOXML round-trip move (preserves all rich content: footnotes, hyperlinks, formatting, images, comments)
   // Supports moving multiple consecutive paragraphs via optional 'count' parameter
   if (name === 'word_move_paragraph') {
     const fromIndex = args.fromIndex;
@@ -207,42 +231,65 @@ async function executeTool(name, args) {
     if (toIndex < 0) throw new Error('toIndex must be non-negative');
     if (count < 1) throw new Error('count must be at least 1');
     if (fromIndex === toIndex && count === 1) throw new Error('fromIndex and toIndex must be different');
+    // Prevent overlapping moves that would cause data loss
+    if (toIndex >= fromIndex && toIndex < fromIndex + count) {
+      throw new Error('toIndex (' + toIndex + ') is inside the source range [' + fromIndex + ', ' + (fromIndex + count - 1) + ']. Move to a position outside the range being moved.');
+    }
     // Validate all indices are in bounds before mutating
     const paraCount = await sendToTaskpane('getParagraphs', {});
     const total = paraCount.count;
     if (fromIndex >= total) throw new Error('fromIndex ' + fromIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
     if (fromIndex + count - 1 >= total) throw new Error('fromIndex + count (' + (fromIndex + count) + ') exceeds paragraph count (' + total + ').');
     if (toIndex >= total) throw new Error('toIndex ' + toIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
-    // Collect all paragraphs to move (text + style)
-    const collected = [];
-    for (let i = 0; i < count; i++) {
-      const details = await sendToTaskpane('getParagraphByIndex', { index: fromIndex + i });
-      collected.push({ text: details.text, style: details.style });
-    }
-    // Delete from last to first to preserve indices during deletion
+    // Step 1: Capture full OOXML of source paragraphs (preserves everything)
+    const ooxmlResult = await sendToTaskpane('getParaOoxml', { index: fromIndex, count: count });
+    const savedOoxml = ooxmlResult.ooxml;
+    // Step 2: Delete source paragraphs (last to first to preserve indices)
     for (let i = count - 1; i >= 0; i--) {
       await sendToTaskpane('deleteParagraph', { index: fromIndex + i });
     }
-    // Adjust destination index after deletions
+    // Step 3: Adjust destination index after deletions (same arithmetic as before)
     let adjustedTo;
     if (fromIndex < toIndex) {
       adjustedTo = toIndex - count;
     } else {
       adjustedTo = toIndex;
     }
-    // Insert in order at destination
-    for (let i = 0; i < collected.length; i++) {
-      if (i === 0) {
-        await sendToTaskpane('insertParagraphAtIndex', { index: adjustedTo, text: collected[i].text, style: collected[i].style, location: location });
-      } else {
-        // After the first insert, the paragraph we just inserted is at a known position.
-        // For 'Before': first para went to adjustedTo, so second goes After adjustedTo.
-        // For 'After': first para went to adjustedTo+1, so second goes After adjustedTo+1.
-        const prevInsertedAt = location === 'Before' ? adjustedTo + (i - 1) : adjustedTo + i;
-        await sendToTaskpane('insertParagraphAtIndex', { index: prevInsertedAt, text: collected[i].text, style: collected[i].style, location: 'After' });
+    // Step 4: Insert OOXML at destination (with restore-on-failure)
+    try {
+      await sendToTaskpane('insertOoxmlAtIndex', { ooxml: savedOoxml, index: adjustedTo, location: location });
+    } catch (insertErr) {
+      // Restore at original position on failure
+      try {
+        await sendToTaskpane('insertOoxmlAtIndex', { ooxml: savedOoxml, index: Math.min(fromIndex, adjustedTo), location: 'Before' });
+      } catch (_restoreErr) {
+        throw new Error('Move failed AND restore failed: ' + insertErr.message + '. Use Ctrl+Z to recover.');
       }
+      throw new Error('Move failed (content restored to original position): ' + insertErr.message);
     }
-    return { content: [{ type: 'text', text: JSON.stringify({ success: true, moved: { from: fromIndex, count, to: adjustedTo, location } }) }] };
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, moved: { from: fromIndex, count, to: adjustedTo, toIndexRequested: toIndex, location } }) }] };
+  }
+
+  // word_copy_paragraph: OOXML round-trip copy (preserves all rich content)
+  if (name === 'word_copy_paragraph') {
+    const fromIndex = args.fromIndex;
+    const toIndex = args.toIndex;
+    const count = args.count || 1;
+    const location = args.location || 'After';
+    if (fromIndex < 0) throw new Error('fromIndex must be non-negative');
+    if (toIndex < 0) throw new Error('toIndex must be non-negative');
+    if (count < 1) throw new Error('count must be at least 1');
+    // Validate all indices are in bounds
+    const paraCount = await sendToTaskpane('getParagraphs', {});
+    const total = paraCount.count;
+    if (fromIndex >= total) throw new Error('fromIndex ' + fromIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    if (fromIndex + count - 1 >= total) throw new Error('fromIndex + count (' + (fromIndex + count) + ') exceeds paragraph count (' + total + ').');
+    if (toIndex >= total) throw new Error('toIndex ' + toIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    // Step 1: Capture full OOXML of source paragraphs
+    const ooxmlResult = await sendToTaskpane('getParaOoxml', { index: fromIndex, count: count });
+    // Step 2: Insert OOXML at destination (no delete — it's a copy)
+    await sendToTaskpane('insertOoxmlAtIndex', { ooxml: ooxmlResult.ooxml, index: toIndex, location: location });
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, copied: { from: fromIndex, count, to: toIndex, location } }) }] };
   }
 
   // word_batch: execute multiple operations in a single call
@@ -256,7 +303,7 @@ async function executeTool(name, args) {
     }
 
     // Partition into taskpane-native ops (have action mapping) vs server-composed ops
-    const SERVER_HANDLED = new Set(['word_insert_equation', 'word_batch', 'word_get_document_outline', 'word_move_paragraph']);
+    const SERVER_HANDLED = new Set(['word_insert_equation', 'word_batch', 'word_get_document_outline', 'word_move_paragraph', 'word_copy_paragraph']);
     const results = [];
 
     // Collect consecutive taskpane-native ops into batches, flush when hitting a server op

package/lib/tools.js

@@ -20,10 +20,11 @@ const tools = [
   { name: 'word_get_paragraphs', description: '[Paragraphs] Get paragraphs with text, style, alignment, and isTocEntry flag. Supports pagination via optional start/end index range (0-based). Returns total paragraph count.', inputSchema: { type: 'object', properties: { start: { type: 'number', description: 'First paragraph index to return (0-based, inclusive)' }, end: { type: 'number', description: 'Last paragraph index (exclusive). Omit to get all from start.' } } } },
   { name: 'word_get_paragraph_by_index', description: '[Paragraphs] Get full details of a single paragraph including font, spacing, indentation, and outline level.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' } }, required: ['index'] } },
   { name: 'word_insert_paragraph', description: '[Paragraphs] Append or prepend a styled paragraph to the document (Start or End only). For inserting at a specific position, use word_insert_paragraph_at_index instead.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where in the document. Default: End' }, style: { type: 'string', description: 'Paragraph style (e.g. "Heading 1", "Normal"). Default: Normal' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['text'] } },
-  { name: 'word_insert_paragraph_at_index', description: '[Paragraphs] Insert a new paragraph Before or After a specific paragraph index. Use this for precise positioning within the document (preferred over word_insert_paragraph for mid-document insertions).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Reference paragraph index (0-based)' }, text: { type: 'string', description: 'Text content for the new paragraph' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the reference paragraph. Default: After' }, style: { type: 'string', description: 'Paragraph style (e.g. "Heading 1", "Normal")' } }, required: ['index', 'text'] } },
+  { name: 'word_insert_paragraph_at_index', description: '[Paragraphs] Insert a new paragraph Before or After a specific paragraph index. Use this for precise positioning within the document (preferred over word_insert_paragraph for mid-document insertions).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Reference paragraph index (0-based)' }, text: { type: 'string', description: 'Text content for the new paragraph' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the reference paragraph. Default: After' }, style: { type: 'string', description: 'Paragraph style (e.g. "Heading 1", "Normal")' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index', 'text'] } },
   { name: 'word_delete_paragraph', description: '[Paragraphs] Delete a paragraph by its 0-based index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' } }, required: ['index'] } },
   { name: 'word_replace_paragraph_text', description: '[Paragraphs] Replace the entire text of a paragraph by index. Preserves style/formatting. Preferred over word_search_and_replace in collaborative editing (targets by position, immune to text-drift).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, text: { type: 'string', description: 'New text content for the paragraph' } }, required: ['index', 'text'] } },
-  { name: 'word_move_paragraph', description: '[Paragraphs] Move a paragraph from one position to another. Handles the delete+insert atomically with correct index adjustment.', inputSchema: { type: 'object', properties: { fromIndex: { type: 'number', description: 'Source paragraph index (0-based)' }, toIndex: { type: 'number', description: 'Destination paragraph index (0-based, position after removal)' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the destination index. Default: After' }, count: { type: 'number', description: 'Number of consecutive paragraphs to move (default: 1). Use to move a heading + its body together.' } }, required: ['fromIndex', 'toIndex'] } },
+  { name: 'word_move_paragraph', description: '[Paragraphs] Move a paragraph from one position to another. Preserves all rich content including footnotes, hyperlinks, formatting, images, and comments.', inputSchema: { type: 'object', properties: { fromIndex: { type: 'number', description: 'Source paragraph index (0-based)' }, toIndex: { type: 'number', description: 'Destination paragraph index (0-based, position after removal)' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the destination index. Default: After' }, count: { type: 'number', description: 'Number of consecutive paragraphs to move (default: 1). Use to move a heading + its body together.' } }, required: ['fromIndex', 'toIndex'] } },
+  { name: 'word_copy_paragraph', description: '[Paragraphs] Copy paragraph(s) to another position. Preserves all rich content including footnotes, hyperlinks, formatting, images, and comments. Source remains unchanged.', inputSchema: { type: 'object', properties: { fromIndex: { type: 'number', description: 'Source paragraph index (0-based)' }, toIndex: { type: 'number', description: 'Destination paragraph index (0-based)' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the destination index. Default: After' }, count: { type: 'number', description: 'Number of consecutive paragraphs to copy (default: 1). Use to copy a heading + its body together.' } }, required: ['fromIndex', 'toIndex'] } },
   { name: 'word_set_paragraph_style', description: '[Paragraphs] Change the style or alignment of a paragraph by index. Alignment accepts: Left, Center, Right, Justified.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index'] } },
   { name: 'word_set_paragraph_spacing', description: '[Paragraphs] Set line spacing (in points: 12=single for 12pt font, 18=1.5x, 24=double), before/after spacing, and indentation on a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, lineSpacing: { type: 'number', description: 'Line spacing in points (e.g. 12=single for 12pt, 18=1.5x, 24=double)' }, spaceBefore: { type: 'number', description: 'Space before paragraph in points' }, spaceAfter: { type: 'number', description: 'Space after paragraph in points' }, firstLineIndent: { type: 'number', description: 'First line indent in points' }, leftIndent: { type: 'number', description: 'Left indent in points' }, rightIndent: { type: 'number', description: 'Right indent in points' } }, required: ['index'] } },
   // 3. SEARCH & TEXT
@@ -34,7 +35,7 @@ const tools = [
   { name: 'word_insert_text_at_selection', description: '[Search] Insert text at the current cursor position, or replace the current selection (set replace=true). Cursor moves to end of inserted text.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, replace: { type: 'boolean', description: 'Replace current selection instead of appending. Default: false' } }, required: ['text'] } },
   { name: 'word_insert_line_break', description: '[Search] Insert a soft line break (Shift+Enter) before or after a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for as anchor point' }, before: { type: 'boolean', description: 'Insert before the match (default: after)' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText'] } },
   // 4. FORMATTING
-  { name: 'word_format_text', description: '[Formatting] Apply formatting (bold, italic, color, size, font) to a text match found by search. Color must be hex (#FF0000). Size: 1-1638pt.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for and format' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, bold: { type: 'boolean' }, italic: { type: 'boolean' }, underline: { type: 'boolean' }, strikeThrough: { type: 'boolean' }, color: { type: 'string', description: 'Hex color e.g. #FF0000' }, highlightColor: { type: 'string' }, size: { type: 'number', description: 'Font size in points (1-1638)' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
+  { name: 'word_format_text', description: '[Formatting] Apply formatting (bold, italic, color, size, font) to a text match found by search. Color must be hex (#FF0000). Size: 1-1638pt.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for and format' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, bold: { type: 'boolean' }, italic: { type: 'boolean' }, underline: { type: 'boolean' }, strikeThrough: { type: 'boolean' }, color: { type: 'string', description: 'Hex color e.g. #FF0000' }, highlightColor: { type: 'string', description: 'Highlight color name (Yellow, Green, Cyan, Magenta, Blue, Red, DarkBlue, DarkCyan, DarkGreen, DarkMagenta, DarkRed, DarkYellow, Gray25, Gray50, Black, White) or hex.' }, size: { type: 'number', description: 'Font size in points (1-1638)' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
   { name: 'word_clear_formatting', description: '[Formatting] Clear direct formatting from a text match, reverting it to the paragraph style defaults.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
   { name: 'word_get_font_info', description: '[Formatting] Inspect font properties (name, size, bold, italic, color) of a text match.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
   // 5. TABLES
@@ -113,7 +114,7 @@ const tools = [
   // 18. EQUATIONS
   { name: 'word_insert_equation', description: '[Equations] Insert a LaTeX math equation as a native editable Word equation. Supports fractions, roots, integrals, matrices, Greek letters, and all standard LaTeX math. Display mode (default) inserts a centered block equation. Inline mode inserts after a search match (provide anchorText) or at cursor position.', inputSchema: { type: 'object', properties: { latex: { type: 'string', description: 'LaTeX math expression (e.g. "\\\\frac{a}{b}", "\\\\int_0^\\\\infty e^{-x} dx")' }, displayMode: { type: 'boolean', description: 'true (default) = centered block equation, false = inline equation' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where to insert display-mode equations. Default: End' }, anchorText: { type: 'string', description: 'For inline mode: search for this text and insert equation after it (avoids manual cursor positioning)' }, occurrence: { type: 'number', description: 'Which anchorText match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive anchor matching. Default: false' } }, required: ['latex'] } },
   // 19. BATCH OPERATIONS
-  { name: 'word_batch', description: '[Batch] Execute multiple operations in a single call to reduce round-trips. Each operation is a tool call object with "tool" and "args" fields. Operations execute sequentially — if one fails, subsequent operations are skipped. Returns results array with success/error for each operation. Consecutive native operations are sent to Word in one message for maximum speed.', inputSchema: { type: 'object', properties: { operations: { type: 'array', items: { type: 'object', properties: { tool: { type: 'string', description: 'Tool name (e.g. "word_insert_paragraph")' }, args: { type: 'object', description: 'Arguments for the tool' } }, required: ['tool'] }, description: 'Array of {tool, args} objects to execute sequentially' } }, required: ['operations'] } },
+  { name: 'word_batch', description: '[Batch] Execute multiple operations in a single call. Each operation is a tool call object with "tool" and "args" fields. Operations execute sequentially — if one fails, subsequent operations are skipped. Returns results array with success/error for each operation.', inputSchema: { type: 'object', properties: { operations: { type: 'array', items: { type: 'object', properties: { tool: { type: 'string', description: 'Tool name (e.g. "word_insert_paragraph")' }, args: { type: 'object', description: 'Arguments for the tool' } }, required: ['tool'] }, description: 'Array of {tool, args} objects to execute sequentially' } }, required: ['operations'] } },
 ];
 
 const toolActionMap = {
@@ -163,7 +164,7 @@ const toolActionMap = {
   word_insert_html: 'insertHtml', word_insert_ooxml: 'insertOoxml',
   word_insert_table_of_contents: 'insertTableOfContents', word_get_fields: 'getFields',
   word_get_page_info: 'getPageInfo',
-  // word_insert_equation, word_batch, word_get_document_outline, word_move_paragraph
+  // word_insert_equation, word_batch, word_get_document_outline, word_move_paragraph, word_copy_paragraph
   // are handled directly in index.js (not via taskpane action map)
 };
 

package/lib/usage-guide.js

@@ -47,7 +47,7 @@ Controls a live Word document through an Office Add-in. All operations execute i
 \`\`\`
 Operations run sequentially. If one fails, the rest are skipped. Maximum 50 per batch.
 
-**Performance:** Consecutive standard operations (paragraphs, search, formatting, tables, etc.) are bundled into a single WebSocket message to Word — executing in one round-trip instead of one per operation. Only server-composed tools (equations, outline, move_paragraph) break the batch into segments.
+**Performance:** Batching is significantly faster than individual calls — use it whenever you have multiple operations to perform.
 
 ## Search Behavior (applies to ALL search-based tools)
 - Case-insensitive by default. Pass \`matchCase: true\` for exact case match.
@@ -67,17 +67,17 @@ The bridge normalizes aliases: Left, Center/Centered, Right, Justify/Justified.
 - \`word_get_comments\` — returns all comments with their anchored document text, author, dates, resolved status
 
 ### Comment + text editing interaction
-**Problem:** \`word_search_and_replace\` on text anchoring a comment collapses the anchor (shrinks to empty). The comment survives but loses its positional context.
+**Problem:** \`word_search_and_replace\` on text anchoring a comment **deletes the comment entirely**. The comment does NOT survive — it is removed along with the anchor text.
 
 **Safe pattern:**
 1. \`word_get_comments\` — identify commented text via anchorText field
 2. If replacement overlaps a comment anchor:
    a. \`word_reply_to_comment\` explaining resolution (if appropriate)
    b. \`word_resolve_comment\`
-   c. THEN replace the text
-3. Resolved thread is preserved as a record
+   c. THEN replace the text (knowing the comment will be deleted)
+3. Resolved thread preserves context in the reply before deletion
 
-**Avoid:** replacing text first (anchor collapses), or deleting+recreating comments (loses author/date/thread).
+**Avoid:** replacing text first without checking comments (silently deletes them), or assuming comments survive anchor replacement (they do not).
 
 ## Tables
 - All indices 0-based: tableIndex, row, col
@@ -116,7 +116,7 @@ After inserting a Table of Contents, heading text appears twice in the document
 - "Word taskpane not connected" — user must open the MCP Word Bridge add-in in Word
 - "Anchor not found" — search text not found in document
 - "Occurrence N not found" — match index out of range
-- Timeout: 30s default, 60s for HTML/OOXML/styles/TOC insertion
+- Operations on large documents or complex content (HTML, OOXML, TOC) may take longer
 
 ## Best Practices
 1. Start with \`word_get_document_outline\` to understand structure
@@ -129,6 +129,7 @@ After inserting a Table of Contents, heading text appears twice in the document
 6. \`word_save\` explicitly after significant changes
 7. Resolve comments rather than deleting them (preserves audit trail)
 8. Use \`word_move_paragraph\` to reorder content (avoids index-shifting bugs with manual delete+insert)
+9. Use \`word_copy_paragraph\` to duplicate content with full fidelity (footnotes, formatting, hyperlinks preserved)
 `;
 
 module.exports = USAGE_GUIDE;

package/manifest.xml

@@ -3,7 +3,7 @@
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="TaskPaneApp">
   <Id>a1b2c3d4-e5f6-7890-abcd-ef1234567890</Id>
-  <Version>1.0.0</Version>
+  <Version>3.5.3</Version>
   <ProviderName>Leonid Mokrushin</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <DisplayName DefaultValue="MCP Word Bridge"/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-word-bridge",
-  "version": "3.5.1",
+  "version": "3.5.3",
   "description": "MCP server for live Word document editing via Office Add-in",
   "main": "index.js",
   "bin": {

package/taskpane-app.js

@@ -30,7 +30,7 @@ Office.onReady(function(info) {
 // --- WebSocket ---
 let ws = null;
 function connectWebSocket() {
-  ws = new WebSocket('wss://localhost:3000/taskpane');
+  ws = new WebSocket('wss://' + window.location.host + '/taskpane');
   ws.onopen = function() {
     wsStatus.textContent = 'WebSocket: connected ✓';
     wsStatus.className = 'status ok';
@@ -70,6 +70,13 @@ async function handleCommand(cmd) {
 // --- Command registry ---
 const commands = {};
 
+// Helper: validate search string length (Word's limit is ~255 characters)
+function checkSearchLength(text) {
+  if (text && text.length > 255) {
+    throw new Error('Search text is too long (max ~255 characters). Shorten the text or use a substring.');
+  }
+}
+
 // == BATCH EXECUTION (runs multiple actions in one WebSocket message) ==
 commands.batchExecute = async (p) => {
   if (!p.operations || !Array.isArray(p.operations) || p.operations.length === 0) {
@@ -175,19 +182,35 @@ commands.getParagraphs = (p) => Word.run(async (ctx) => {
   if (p.start !== undefined && p.start < 0) throw new Error('start index must be non-negative');
   if (p.end !== undefined && p.end < 0) throw new Error('end index must be non-negative');
   const paragraphs = ctx.document.body.paragraphs;
-  paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,parentTableCellOrNullObject');
-  await ctx.sync();
+  // Try loading all properties including parentTableCellOrNullObject
+  // If merged cells cause a failure, fall back to loading without it
+  let hasTableInfo = true;
+  try {
+    paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,outlineLevel,parentTableCellOrNullObject');
+    await ctx.sync();
+  } catch (_e) {
+    hasTableInfo = false;
+    paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,outlineLevel');
+    await ctx.sync();
+  }
   const start = p.start !== undefined ? p.start : 0;
   const end = p.end !== undefined ? p.end : paragraphs.items.length;
   if (start > end) throw new Error('start (' + start + ') must be less than or equal to end (' + end + ')');
   const items = [];
   for (let i = start; i < Math.min(end, paragraphs.items.length); i++) {
     const para = paragraphs.items[i];
-    const inTable = para.parentTableCellOrNullObject && !para.parentTableCellOrNullObject.isNullObject;
+    let inTable = false;
+    if (hasTableInfo) {
+      try { inTable = para.parentTableCellOrNullObject && !para.parentTableCellOrNullObject.isNullObject; } catch (_e) { inTable = false; }
+    }
     const isTocEntry = !!(para.style && para.style.startsWith('TOC')) || (para.style === '' && /\t\d+$/.test(para.text));
-    items.push({ index: i, text: para.text, style: para.style, alignment: para.alignment, isListItem: para.isListItem, inTable: inTable, isTocEntry: isTocEntry });
+    items.push({ index: i, text: para.text, style: para.style, alignment: para.alignment, isListItem: para.isListItem, inTable: inTable, isTocEntry: isTocEntry, outlineLevel: para.outlineLevel });
+  }
+  const result = { count: paragraphs.items.length, paragraphs: items };
+  if (p.start !== undefined && p.start >= paragraphs.items.length) {
+    result.warning = 'start index (' + p.start + ') is beyond the last paragraph. Document has ' + paragraphs.items.length + ' paragraphs (valid indices: 0-' + (paragraphs.items.length - 1) + ').';
   }
-  return { count: paragraphs.items.length, paragraphs: items };
+  return result;
 });
 
 commands.insertParagraph = (p) => Word.run(async (ctx) => {
@@ -253,8 +276,16 @@ commands.deleteParagraph = (p) => Word.run(async (ctx) => {
   paragraphs.load('text');
   await ctx.sync();
   if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  const countBefore = paragraphs.items.length;
   paragraphs.items[p.index].delete();
-  await ctx.sync();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Cannot delete paragraph ' + p.index + '. It may be a TOC field entry or inside a protected region.');
+    }
+    throw e;
+  }
   // Move cursor to the paragraph that now occupies this position (or previous if at end)
   const parasAfter = ctx.document.body.paragraphs;
   parasAfter.load('text');
@@ -264,7 +295,11 @@ commands.deleteParagraph = (p) => Word.run(async (ctx) => {
     parasAfter.items[cursorIdx].getRange('Start').select();
     await ctx.sync();
   }
-  return { success: true };
+  const result = { success: true };
+  if (parasAfter.items.length >= countBefore) {
+    result.warning = 'Paragraph was cleared but not removed (Word requires at least one paragraph).';
+  }
+  return result;
 });
 
 commands.setParagraphStyle = (p) => Word.run(async (ctx) => {
@@ -326,6 +361,8 @@ commands.search = (p) => Word.run(async (ctx) => {
 });
 
 commands.searchAndReplace = (p) => Word.run(async (ctx) => {
+  if (!p.find || typeof p.find !== 'string' || p.find.trim() === '') throw new Error('find string cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.find);
   const results = ctx.document.body.search(p.find, { matchCase: p.matchCase || false, matchWholeWord: p.matchWholeWord || false });
   results.load('text');
   await ctx.sync();
@@ -347,6 +384,7 @@ commands.insertText = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
   const anchor = p.after || p.before;
   if (!anchor) throw new Error('Either "after" or "before" anchor text must be provided');
+  checkSearchLength(anchor);
   const results = ctx.document.body.search(anchor, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -361,27 +399,14 @@ commands.insertText = (p) => Word.run(async (ctx) => {
   return { success: true };
 });
 
-commands.getSelection = () => Word.run(async (ctx) => {
-  const sel = ctx.document.getSelection();
-  sel.load('text,style');
-  await ctx.sync();
-  return { text: sel.text, style: sel.style };
-});
-
-commands.replaceSelection = (p) => Word.run(async (ctx) => {
-  const sel = ctx.document.getSelection();
-  const inserted = sel.insertText(p.text, Word.InsertLocation.replace);
-  inserted.getRange('End').select();
-  await ctx.sync();
-  return { success: true };
-});
-
 // == FORMATTING ==
 commands.formatRange = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
+  if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('text to format cannot be empty. Provide a non-empty search string.');
   if (p.size !== undefined && p.size <= 0) throw new Error('size must be positive');
   if (p.size !== undefined && p.size > 1638) throw new Error('size must not exceed 1638 points (Word maximum)');
   if (p.color && !/^#[0-9A-Fa-f]{6}$/.test(p.color)) throw new Error('color must be a valid hex color (e.g. #FF0000)');
+  checkSearchLength(p.text);
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font');
   await ctx.sync();
@@ -511,17 +536,30 @@ commands.deleteTableRow = (p) => Word.run(async (ctx) => {
 commands.insertList = (p) => Word.run(async (ctx) => {
   if (!p.items || p.items.length === 0) throw new Error('items array must not be empty');
   const body = ctx.document.body;
-  // Check if last paragraph is a list item — if so, insert a non-list separator
-  const lastPara = body.paragraphs.getLast();
-  lastPara.load('isListItem');
-  await ctx.sync();
-  if (lastPara.isListItem && (p.location || 'End') === 'End') {
-    const sep = body.insertParagraph('', 'End');
-    sep.style = 'Normal';
-    sep.detachFromList();
+  const location = p.location || 'End';
+  // Check if adjacent paragraph is a list item — if so, insert a non-list separator
+  if (location === 'End') {
+    const lastPara = body.paragraphs.getLast();
+    lastPara.load('isListItem');
+    await ctx.sync();
+    if (lastPara.isListItem) {
+      const sep = body.insertParagraph('', 'End');
+      sep.style = 'Normal';
+      sep.detachFromList();
+      await ctx.sync();
+    }
+  } else if (location === 'Start') {
+    const firstPara = body.paragraphs.getFirst();
+    firstPara.load('isListItem');
     await ctx.sync();
+    if (firstPara.isListItem) {
+      const sep = body.insertParagraph('', 'Start');
+      sep.style = 'Normal';
+      sep.detachFromList();
+      await ctx.sync();
+    }
   }
-  const para = body.insertParagraph(p.items[0], p.location || 'End');
+  const para = body.insertParagraph(p.items[0], location);
   para.style = 'Normal';
   await ctx.sync();
   const list = para.startNewList();
@@ -545,6 +583,8 @@ commands.insertList = (p) => Word.run(async (ctx) => {
 commands.addComment = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
   if (!p.comment || typeof p.comment !== 'string' || p.comment.trim() === '') throw new Error('comment text must be a non-empty string');
+  if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -610,6 +650,8 @@ commands.deleteComment = (p) => Word.run(async (ctx) => {
 // == FOOTNOTES & ENDNOTES ==
 commands.insertFootnote = (p) => Word.run(async (ctx) => {
   if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('Footnote text must be a non-empty string');
+  if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -625,6 +667,8 @@ commands.insertFootnote = (p) => Word.run(async (ctx) => {
 
 commands.insertEndnote = (p) => Word.run(async (ctx) => {
   if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('Endnote text must be a non-empty string');
+  if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -847,6 +891,10 @@ commands.getBookmarks = () => Word.run(async (ctx) => {
 
 commands.insertBookmark = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
+  if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  if (!p.name || typeof p.name !== 'string' || p.name.trim() === '') throw new Error('Bookmark name must be a non-empty string.');
+  if (!/^[A-Za-z_]\w*$/.test(p.name)) throw new Error('Invalid bookmark name: "' + p.name + '". Names must start with a letter or underscore and contain only letters, numbers, and underscores (no spaces).');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   // Check for existing bookmark with same name
@@ -885,7 +933,8 @@ commands.getStyles = () => Word.run(async (ctx) => {
   styles.load('nameLocal,type,builtIn');
   await ctx.sync();
   const items = styles.items.map(s => ({ name: s.nameLocal, type: s.type, builtIn: s.builtIn }));
-  return { count: items.length, styles: items.slice(0, 80) };
+  const returned = items.slice(0, 80);
+  return { count: returned.length, total: items.length, styles: returned };
 });
 
 // == COAUTHORING (Desktop only) ==
@@ -976,7 +1025,14 @@ commands.insertPageBreak = (p) => Word.run(async (ctx) => {
     lastPara.insertBreak('Page', 'After');
     lastPara.getRange('End').select();
   }
-  await ctx.sync();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Cannot insert page break at paragraph ' + (p.paragraphIndex !== undefined ? p.paragraphIndex : 'end') + '. The paragraph may be inside a table cell (page breaks are not allowed inside tables).');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
@@ -1014,11 +1070,15 @@ commands.insertHyperlink = (p) => Word.run(async (ctx) => {
   if (!p.url || !/^https?:\/\/.+/i.test(p.url)) throw new Error('URL must be a valid HTTP or HTTPS URL (e.g. https://example.com)');
   // Reject URLs containing characters that must be percent-encoded (RFC 3986 unsafe chars)
   if (/[<>"{}|\\^`]/.test(p.url)) throw new Error('Malformed URL: "' + p.url + '". URL contains invalid characters that must be percent-encoded.');
+  if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
   if (results.items.length === 0) throw new Error('Anchor not found: ' + p.anchorText);
-  const target = results.items[p.occurrence || 0];
+  const idx = p.occurrence || 0;
+  if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+  const target = results.items[idx];
   target.hyperlink = p.url;
   target.getRange('End').select();
   await ctx.sync();
@@ -1028,9 +1088,20 @@ commands.insertHyperlink = (p) => Word.run(async (ctx) => {
 // == FIELDS ==
 commands.getFields = () => Word.run(async (ctx) => {
   const fields = ctx.document.body.fields;
-  fields.load('code,result,type');
+  fields.load('code,type');
+  await ctx.sync();
+  const items = [];
+  for (let i = 0; i < fields.items.length; i++) {
+    const f = fields.items[i];
+    f.result.load('text');
+  }
   await ctx.sync();
-  const items = fields.items.map((f, i) => ({ index: i, code: (f.code || '').replace(/[\u0001\u0013\u0014\u0015]/g, '').trim(), result: f.result, type: f.type }));
+  for (let i = 0; i < fields.items.length; i++) {
+    const f = fields.items[i];
+    const code = (f.code || '').replace(/[\u0001\u0013\u0014\u0015]/g, '').trim();
+    const resultText = (f.result.text || '').replace(/[\u0001\u0002\u0013\u0014\u0015]/g, '').trim();
+    items.push({ index: i, code: code, result: resultText, type: f.type });
+  }
   return { count: items.length, fields: items };
 });
 
@@ -1039,11 +1110,15 @@ commands.insertContentControl = (p) => Word.run(async (ctx) => {
   const ccType = p.type || 'RichText';
   let range;
   if (p.anchorText) {
+    if (typeof p.anchorText === 'string' && p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string or omit the parameter to use the current selection.');
+    checkSearchLength(p.anchorText);
     const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
     results.load('text');
     await ctx.sync();
     if (results.items.length === 0) throw new Error('Anchor not found: ' + p.anchorText);
-    range = results.items[p.occurrence || 0];
+    const idx = p.occurrence || 0;
+    if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+    range = results.items[idx];
   } else {
     range = ctx.document.getSelection();
   }
@@ -1099,6 +1174,8 @@ commands.getPageLayout = (p) => Word.run(async (ctx) => {
 // == FONT INFO ==
 commands.getFontInfo = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
+  if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('text cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.text);
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font');
   await ctx.sync();
@@ -1151,6 +1228,10 @@ commands.insertHtml = (p) => Word.run(async (ctx) => {
 });
 
 commands.insertOoxml = (p) => Word.run(async (ctx) => {
+  if (!p.ooxml || typeof p.ooxml !== 'string' || p.ooxml.trim() === '') throw new Error('ooxml parameter must be a non-empty string');
+  if (!p.ooxml.includes('pkg:package') && !p.ooxml.includes('pkg:part')) {
+    throw new Error('Invalid OOXML: missing pkg:package structure. The XML must be a valid Office Open XML flat package (containing pkg:package and pkg:part elements with a word/document.xml part).');
+  }
   const body = ctx.document.body;
   const range = body.insertOoxml(p.ooxml, p.location || 'End');
   range.getRange('End').select();
@@ -1225,23 +1306,61 @@ commands.replaceParagraphText = (p) => Word.run(async (ctx) => {
   const para = paragraphs.items[p.index];
   const inserted = para.insertText(p.text, Word.InsertLocation.replace);
   inserted.getRange('End').select();
-  await ctx.sync();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Cannot replace text of paragraph ' + p.index + '. It may be a TOC field entry or inside a protected region.');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
 commands.insertParagraphAtIndex = (p) => Word.run(async (ctx) => {
   if (p.index < 0) throw new Error('Index must be non-negative');
+  // Normalize and validate alignment
+  const ALIGNMENT_MAP = { 'Left': 'Left', 'Center': 'Centered', 'Centered': 'Centered', 'Right': 'Right', 'Justify': 'Justified', 'Justified': 'Justified' };
+  let alignment = null;
+  if (p.alignment) {
+    alignment = ALIGNMENT_MAP[p.alignment];
+    if (!alignment) {
+      throw new Error('Invalid alignment: "' + p.alignment + '". Valid values: Left, Center, Right, Justified');
+    }
+  }
   const paragraphs = ctx.document.body.paragraphs;
-  paragraphs.load('text');
+  paragraphs.load('text,parentTableCellOrNullObject');
   await ctx.sync();
   if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  let inTable = false;
+  try { inTable = paragraphs.items[p.index].parentTableCellOrNullObject && !paragraphs.items[p.index].parentTableCellOrNullObject.isNullObject; } catch (_e) { /* ignore */ }
+  // Validate style exists (if provided)
+  const styleName = p.style || 'Normal';
+  if (p.style) {
+    const styleObj = ctx.document.getStyles().getByNameOrNullObject(p.style);
+    styleObj.load('nameLocal');
+    await ctx.sync();
+    if (styleObj.isNullObject) {
+      throw new Error('Style not found: "' + p.style + '". Use word_get_styles to see available styles.');
+    }
+  }
   const ref = paragraphs.items[p.index];
   const location = p.location === 'Before' ? Word.InsertLocation.before : Word.InsertLocation.after;
   const newPara = ref.insertParagraph(p.text, location);
-  newPara.style = p.style || 'Normal';
+  newPara.style = styleName;
+  await ctx.sync();
+  // Apply alignment in a separate sync
+  if (alignment) {
+    newPara.alignment = alignment;
+    await ctx.sync();
+  }
   newPara.getRange('End').select();
   await ctx.sync();
-  return { success: true };
+  const result = { success: true };
+  if (inTable) {
+    result.warning = 'Paragraph inserted inside a table cell. This creates a multi-paragraph cell which may not be intended.';
+  }
+  return result;
 });
 
 // == BOOKMARK NAVIGATION ==
@@ -1318,13 +1437,23 @@ commands.mergeTableCells = (p) => Word.run(async (ctx) => {
 commands.splitTableCell = (p) => Word.run(async (ctx) => {
   if (p.rowCount !== undefined && p.rowCount <= 0) throw new Error('rowCount must be a positive integer (minimum 1)');
   if (p.colCount !== undefined && p.colCount <= 0) throw new Error('colCount must be a positive integer (minimum 1)');
+  if (p.tableIndex < 0) throw new Error('Table index must be non-negative');
+  if (p.row < 0) throw new Error('Row index must be non-negative');
+  if (p.col < 0) throw new Error('Column index must be non-negative');
   const tables = ctx.document.body.tables;
   tables.load('rowCount');
   await ctx.sync();
-  if (p.tableIndex >= tables.items.length) throw new Error('Table index out of range');
-  const cell = tables.items[p.tableIndex].getCell(p.row, p.col);
-  cell.split(p.rowCount || 1, p.colCount || 2);
-  await ctx.sync();
+  if (p.tableIndex >= tables.items.length) throw new Error('Table index out of range. Document has ' + tables.items.length + ' table(s).');
+  try {
+    const cell = tables.items[p.tableIndex].getCell(p.row, p.col);
+    cell.split(p.rowCount || 1, p.colCount || 2);
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('ItemNotFound')) {
+      throw new Error('Cell not found at row ' + p.row + ', col ' + p.col + '. Use word_get_table_data to inspect the table.');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
@@ -1404,6 +1533,8 @@ commands.getChangeTrackingMode = () => Word.run(async (ctx) => {
 // == CLEAR FORMATTING ==
 commands.clearFormatting = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
+  if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('text cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.text);
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font,style');
   await ctx.sync();
@@ -1447,7 +1578,9 @@ commands.getPageInfo = async () => {
     allParas.load('text,style');
     await ctx.sync();
     const pageDetails = [];
-    const usedIndices = new Set();
+    // Forward-only cursor: pages are sequential, so each page's paragraphs
+    // must start at or after the previous page's last matched index.
+    let nextStart = 0;
     for (let i = 0; i < pages.items.length; i++) {
       const page = pages.items[i];
       page.load('index,height,width');
@@ -1458,11 +1591,11 @@ commands.getPageInfo = async () => {
       let lastIdx = -1;
       for (let j = 0; j < paras.items.length; j++) {
         const p = paras.items[j];
-        for (let k = 0; k < allParas.items.length; k++) {
-          if (!usedIndices.has(k) && allParas.items[k].text === p.text && allParas.items[k].style === p.style) {
-            usedIndices.add(k);
+        for (let k = nextStart; k < allParas.items.length; k++) {
+          if (allParas.items[k].text === p.text && allParas.items[k].style === p.style) {
             if (firstIdx === -1) firstIdx = k;
             lastIdx = k;
+            nextStart = k + 1;
             break;
           }
         }
@@ -1530,6 +1663,7 @@ commands.deleteImage = (p) => Word.run(async (ctx) => {
 
 // == TABLE CELL SHADING ==
 commands.setTableCellShading = (p) => Word.run(async (ctx) => {
+  if (!/^#[0-9A-Fa-f]{6}$/.test(p.color)) throw new Error('color must be a valid hex color (e.g. #FFD700)');
   const tables = ctx.document.body.tables;
   tables.load('rowCount');
   await ctx.sync();
@@ -1568,11 +1702,15 @@ commands.getHyperlinks = () => Word.run(async (ctx) => {
 });
 
 commands.removeHyperlink = (p) => Word.run(async (ctx) => {
+  if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('hyperlink');
   await ctx.sync();
   if (results.items.length === 0) throw new Error('Text not found: ' + p.anchorText);
-  const target = results.items[p.occurrence || 0];
+  const idx = p.occurrence || 0;
+  if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+  const target = results.items[idx];
   target.hyperlink = '';
   target.getRange('End').select();
   await ctx.sync();
@@ -1652,14 +1790,65 @@ commands.setListLevel = (p) => Word.run(async (ctx) => {
 
 // == LINE BREAK ==
 commands.insertLineBreak = (p) => Word.run(async (ctx) => {
+  if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
+  if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
   if (results.items.length === 0) throw new Error('Anchor not found: ' + p.anchorText);
-  const target = results.items[p.occurrence || 0];
+  const idx = p.occurrence || 0;
+  if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+  const target = results.items[idx];
   const loc = p.before ? Word.InsertLocation.before : Word.InsertLocation.after;
   target.insertBreak('Line', loc);
   target.getRange('End').select();
   await ctx.sync();
   return { success: true };
 });
+
+// == OOXML ROUND-TRIP (for move/copy paragraph with full fidelity) ==
+commands.getParaOoxml = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
+  const count = p.count || 1;
+  if (count < 1) throw new Error('count must be at least 1');
+  const paragraphs = ctx.document.body.paragraphs;
+  paragraphs.load('text');
+  await ctx.sync();
+  if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  if (p.index + count - 1 >= paragraphs.items.length) throw new Error('index + count (' + (p.index + count) + ') exceeds paragraph count (' + paragraphs.items.length + ').');
+  let range;
+  if (count === 1) {
+    range = paragraphs.items[p.index].getRange('Whole');
+  } else {
+    const firstRange = paragraphs.items[p.index].getRange('Whole');
+    const lastRange = paragraphs.items[p.index + count - 1].getRange('Whole');
+    range = firstRange.expandTo(lastRange);
+  }
+  const ooxml = range.getOoxml();
+  await ctx.sync();
+  return { ooxml: ooxml.value };
+});
+
+commands.insertOoxmlAtIndex = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
+  if (!p.ooxml || typeof p.ooxml !== 'string' || p.ooxml.trim() === '') throw new Error('ooxml parameter must be a non-empty string');
+  const paragraphs = ctx.document.body.paragraphs;
+  paragraphs.load('text');
+  await ctx.sync();
+  if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  const ref = paragraphs.items[p.index];
+  const location = p.location === 'Before' ? 'Before' : 'After';
+  const range = ref.getRange(location);
+  const inserted = range.insertOoxml(p.ooxml, 'Replace');
+  inserted.getRange('End').select();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Invalid OOXML or cannot insert at paragraph ' + p.index + '. Ensure the XML follows the Office Open XML package structure.');
+    }
+    throw e;
+  }
+  return { success: true };
+});