mcp-word-bridge 3.4.1 → 3.4.2

package/index.js

@@ -134,7 +134,7 @@ function sendToTaskpane(action, params) {
 }
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.4.1' },
+  { name: 'mcp-word-bridge', version: '3.4.2' },
   { capabilities: { tools: {}, resources: {} } }
 );
 

package/lib/tools.js

@@ -23,18 +23,18 @@ const tools = [
   { name: 'word_set_paragraph_style', description: 'Change the style or alignment of a paragraph by index. Alignment accepts: Left, Center, Right, Justified.', inputSchema: { type: 'object', properties: { index: { type: 'number' }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index'] } },
   { name: 'word_set_paragraph_spacing', description: 'Set line spacing (in points, e.g. 12=single for 12pt font, 24=double), before/after spacing (points), and indentation (points) on a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' }, 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
-  { name: 'word_search', description: 'Search for text in the document (case-insensitive by default). Returns match count and up to 30 matches with their text.', inputSchema: { type: 'object', properties: { query: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive search. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['query'] } },
-  { name: 'word_search_and_replace', description: 'Find and replace all occurrences of text (case-insensitive by default). Returns replacement count.', inputSchema: { type: 'object', properties: { find: { type: 'string' }, replace: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['find', 'replace'] } },
+  { name: 'word_search', description: 'Search for text in the document (case-insensitive by default). Query must be non-empty and ≤255 chars. Returns match count and up to 30 matches with their text. Supports Word wildcards (e.g. ^p for paragraph mark).', inputSchema: { type: 'object', properties: { query: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive search. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['query'] } },
+  { name: 'word_search_and_replace', description: 'Find and replace all occurrences of text (case-insensitive by default). Returns replacement count. Note: if find equals replace, Word still reports it as a replacement (the text is rewritten in-place). Supports Word wildcards (e.g. ^p for paragraph mark).', inputSchema: { type: 'object', properties: { find: { type: 'string' }, replace: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['find', 'replace'] } },
   { name: 'word_insert_text', description: 'Insert text before or after a search match. Provide "after" OR "before" (not both) as the anchor string to locate.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, after: { type: 'string' }, before: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
   { name: 'word_get_selection_info', description: 'Get the current selection text with full font and style details.', inputSchema: { type: 'object', properties: {} } },
   { name: 'word_insert_text_at_selection', description: 'Insert text at the current cursor position, or replace the current selection (set replace=true).', 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: 'Insert a soft line break (Shift+Enter) before or after a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, before: { type: 'boolean' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText'] } },
   // 4. FORMATTING
-  { name: 'word_format_text', description: 'Apply formatting (bold, italic, color, size, font) to a text match found by search.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, 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' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
+  { name: 'word_format_text', description: 'Apply formatting (bold, italic, color, size, font) to a text match found by search. Color must be hex (e.g. #FF0000). Size range: 1-1638 points.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, 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 (case-insensitive)' } }, required: ['text'] } },
   { name: 'word_clear_formatting', description: 'Clear direct formatting from a text match, reverting it to the paragraph style defaults.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
   { name: 'word_get_font_info', description: 'Inspect font properties (name, size, bold, italic, color) of a text match.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
   // 5. TABLES
-  { name: 'word_insert_table', description: 'Insert a table with data. Provide rows, cols, and data as array of arrays (e.g. [["A","B"],["C","D"]]).', inputSchema: { type: 'object', properties: { rows: { type: 'number' }, cols: { type: 'number' }, data: { type: 'array', items: { type: 'array', items: { type: 'string' } } }, location: { type: 'string', enum: ['Start', 'End'] }, style: { type: 'string' }, headerRowCount: { type: 'number' } }, required: ['rows', 'cols'] } },
+  { name: 'word_insert_table', description: 'Insert a table with data. Provide rows (1-500), cols (1-63), and data as array of arrays (e.g. [["A","B"],["C","D"]]).', inputSchema: { type: 'object', properties: { rows: { type: 'number' }, cols: { type: 'number' }, data: { type: 'array', items: { type: 'array', items: { type: 'string' } } }, location: { type: 'string', enum: ['Start', 'End'] }, style: { type: 'string' }, headerRowCount: { type: 'number' } }, required: ['rows', 'cols'] } },
   { name: 'word_get_tables', description: 'Get all tables with row counts, styles, and cell values.', inputSchema: { type: 'object', properties: {} } },
   { name: 'word_get_table_data', description: 'Get all cell values from a specific table by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
   { name: 'word_set_table_cell', description: 'Set text in a specific table cell by tableIndex, row, and col.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, text: { type: 'string' } }, required: ['tableIndex', 'row', 'col', 'text'] } },
@@ -77,7 +77,7 @@ const tools = [
   { name: 'word_set_content_control_text', description: 'Set text in a content control by ID or tag.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, tag: { type: 'string' }, text: { type: 'string' } }, required: ['text'] } },
   // 11. BOOKMARKS
   { name: 'word_get_bookmarks', description: 'Get all bookmark names.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_bookmark', description: 'Insert a bookmark at anchor text.', inputSchema: { type: 'object', properties: { name: { type: 'string' }, anchorText: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['name', 'anchorText'] } },
+  { name: 'word_insert_bookmark', description: 'Insert a bookmark at anchor text. If a bookmark with the same name already exists, it is moved to the new location (returns warning).', inputSchema: { type: 'object', properties: { name: { type: 'string' }, anchorText: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['name', 'anchorText'] } },
   { name: 'word_delete_bookmark', description: 'Delete a bookmark by name.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
   { name: 'word_go_to_bookmark', description: 'Navigate to a bookmark and select its text range.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
   { name: 'word_get_bookmark_text', description: 'Get the text content within a named bookmark.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },

package/package.json

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

package/taskpane-app.js

@@ -138,9 +138,12 @@ commands.setDocumentProperties = (p) => Word.run(async (ctx) => {
 
 commands.setChangeTracking = (p) => Word.run(async (ctx) => {
   // mode: 'TrackAll', 'TrackMineOnly', or 'Off'
-  ctx.document.changeTrackingMode = p.mode || 'TrackAll';
+  const validModes = ['TrackAll', 'TrackMineOnly', 'Off'];
+  const mode = p.mode || 'TrackAll';
+  if (!validModes.includes(mode)) throw new Error('Invalid mode: "' + mode + '". Valid values: TrackAll, TrackMineOnly, Off');
+  ctx.document.changeTrackingMode = mode;
   await ctx.sync();
-  return { success: true, mode: p.mode || 'TrackAll' };
+  return { success: true, mode: mode };
 });
 
 // == PARAGRAPHS ==
@@ -150,8 +153,9 @@ commands.getParagraphs = (p) => Word.run(async (ctx) => {
   const paragraphs = ctx.document.body.paragraphs;
   paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,parentTableCellOrNullObject');
   await ctx.sync();
-  const start = p.start || 0;
-  const end = p.end || paragraphs.items.length;
+  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];
@@ -163,6 +167,10 @@ commands.getParagraphs = (p) => Word.run(async (ctx) => {
 });
 
 commands.insertParagraph = (p) => Word.run(async (ctx) => {
+  // Validate location enum
+  if (p.location && p.location !== 'Start' && p.location !== 'End') {
+    throw new Error('Invalid location: "' + p.location + '". Valid values: Start, End');
+  }
   // Normalize and validate alignment before any document mutation
   // Official Word.Alignment enum: Left, Centered, Right, Justified (Mixed/Unknown are read-only)
   const ALIGNMENT_MAP = { 'Left': 'Left', 'Center': 'Centered', 'Centered': 'Centered', 'Right': 'Right', 'Justify': 'Justified', 'Justified': 'Justified' };
@@ -267,9 +275,17 @@ commands.setParagraphStyle = (p) => Word.run(async (ctx) => {
 
 // == SEARCH & REPLACE ==
 commands.search = (p) => Word.run(async (ctx) => {
+  if (!p.query || typeof p.query !== 'string' || p.query.trim() === '') throw new Error('Search query cannot be empty. Provide a non-empty search string.');
   const results = ctx.document.body.search(p.query, { matchCase: p.matchCase || false, matchWholeWord: p.matchWholeWord || false });
   results.load('text');
-  await ctx.sync();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('SearchStringInvalidOrTooLong')) {
+      throw new Error('Search query is too long (max ~255 characters). Shorten the query text.');
+    }
+    throw e;
+  }
   return { count: results.items.length, matches: results.items.slice(0, 30).map((r, i) => ({ index: i, text: r.text })) };
 });
 
@@ -327,6 +343,9 @@ commands.replaceSelection = (p) => Word.run(async (ctx) => {
 // == 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.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)');
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font');
   await ctx.sync();
@@ -350,6 +369,11 @@ commands.formatRange = (p) => Word.run(async (ctx) => {
 
 // == TABLES ==
 commands.insertTable = (p) => Word.run(async (ctx) => {
+  // Validate rows and cols
+  if (!p.rows || p.rows <= 0) throw new Error('rows must be a positive integer (minimum 1)');
+  if (!p.cols || p.cols <= 0) throw new Error('cols must be a positive integer (minimum 1)');
+  if (p.cols > 63) throw new Error('cols must not exceed 63 (Word maximum column limit)');
+  if (p.rows > 500) throw new Error('rows must not exceed 500 (practical limit for performance)');
   // Validate data dimensions match rows/cols if data is provided
   if (p.data) {
     if (!Array.isArray(p.data)) throw new Error('data must be an array of arrays');
@@ -383,6 +407,7 @@ commands.getTables = () => Word.run(async (ctx) => {
 });
 
 commands.getTableData = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Table index must be non-negative');
   const tables = ctx.document.body.tables;
   tables.load('rowCount,values');
   await ctx.sync();
@@ -412,11 +437,16 @@ commands.setTableCell = (p) => Word.run(async (ctx) => {
 });
 
 commands.addTableRow = (p) => Word.run(async (ctx) => {
+  if (p.tableIndex < 0) throw new Error('Table index must be non-negative');
   const tables = ctx.document.body.tables;
-  tables.load('rowCount');
+  tables.load('rowCount,values');
   await ctx.sync();
   if (p.tableIndex >= tables.items.length) throw new Error('Table index out of range');
   const table = tables.items[p.tableIndex];
+  if (p.values && p.values.length > 0) {
+    const colCount = table.values[0].length;
+    if (p.values.length > colCount) throw new Error('values has ' + p.values.length + ' items but table only has ' + colCount + ' columns.');
+  }
   table.addRows(p.location || 'End', 1, p.values ? [p.values] : undefined);
   await ctx.sync();
   // Move cursor to end of table after adding row
@@ -427,6 +457,8 @@ commands.addTableRow = (p) => Word.run(async (ctx) => {
 });
 
 commands.deleteTableRow = (p) => Word.run(async (ctx) => {
+  if (p.tableIndex < 0) throw new Error('Table index must be non-negative');
+  if (p.rowIndex < 0) throw new Error('Row index must be non-negative');
   const tables = ctx.document.body.tables;
   tables.load('rowCount');
   await ctx.sync();
@@ -477,6 +509,7 @@ commands.insertList = (p) => Word.run(async (ctx) => {
 // == COMMENTS ==
 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');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -541,6 +574,7 @@ 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');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -555,6 +589,7 @@ 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');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -572,6 +607,9 @@ commands.getFootnotes = () => Word.run(async (ctx) => {
   const footnotes = ctx.document.body.footnotes;
   footnotes.load('items');
   await ctx.sync();
+  // Re-load to avoid stale collection after recent insertions
+  footnotes.load('items');
+  await ctx.sync();
   const items = [];
   for (const fn of footnotes.items) {
     fn.body.load('text');
@@ -585,6 +623,9 @@ commands.getEndnotes = () => Word.run(async (ctx) => {
   const endnotes = ctx.document.body.endnotes;
   endnotes.load('items');
   await ctx.sync();
+  // Re-load to avoid stale collection after recent insertions
+  endnotes.load('items');
+  await ctx.sync();
   const items = [];
   for (const en of endnotes.items) {
     en.body.load('text');
@@ -604,9 +645,13 @@ commands.getTrackedChanges = () => Word.run(async (ctx) => {
 });
 
 commands.acceptTrackedChange = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
   const changes = ctx.document.body.getTrackedChanges();
   changes.load('items');
   await ctx.sync();
+  // Re-load to avoid stale collection after recent document mutations
+  changes.load('items');
+  await ctx.sync();
   if (p.index >= changes.items.length) throw new Error('Change index out of range. Document has ' + changes.items.length + ' tracked change(s).');
   changes.items[p.index].accept();
   await ctx.sync();
@@ -614,9 +659,13 @@ commands.acceptTrackedChange = (p) => Word.run(async (ctx) => {
 });
 
 commands.rejectTrackedChange = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
   const changes = ctx.document.body.getTrackedChanges();
   changes.load('items');
   await ctx.sync();
+  // Re-load to avoid stale collection after recent document mutations
+  changes.load('items');
+  await ctx.sync();
   if (p.index >= changes.items.length) throw new Error('Change index out of range. Document has ' + changes.items.length + ' tracked change(s).');
   changes.items[p.index].reject();
   await ctx.sync();
@@ -682,7 +731,7 @@ commands.setContentControlText = (p) => Word.run(async (ctx) => {
       }
     }
   }
-  if (!target) throw new Error('Content control not found. Use word_get_content_controls to list available controls.');
+  if (!target) throw new Error('Content control not found. Provide "id" or "tag" to identify the control. Use word_get_content_controls to list available controls.');
   const inserted = target.insertText(p.text, Word.InsertLocation.replace);
   inserted.getRange('End').select();
   await ctx.sync();
@@ -694,7 +743,9 @@ commands.getHeaderFooter = (p) => Word.run(async (ctx) => {
   const sections = ctx.document.sections;
   sections.load('items');
   await ctx.sync();
-  const section = sections.items[p.sectionIndex || 0];
+  const idx = p.sectionIndex || 0;
+  if (idx < 0 || idx >= sections.items.length) throw new Error('Section index out of range. Document has ' + sections.items.length + ' section(s) (0-indexed).');
+  const section = sections.items[idx];
   const target = p.type === 'footer' ? section.getFooter(p.headerType || 'Primary') : section.getHeader(p.headerType || 'Primary');
   target.load('text');
   await ctx.sync();
@@ -705,7 +756,9 @@ commands.setHeaderFooter = (p) => Word.run(async (ctx) => {
   const sections = ctx.document.sections;
   sections.load('items');
   await ctx.sync();
-  const section = sections.items[p.sectionIndex || 0];
+  const idx = p.sectionIndex || 0;
+  if (idx < 0 || idx >= sections.items.length) throw new Error('Section index out of range. Document has ' + sections.items.length + ' section(s) (0-indexed).');
+  const section = sections.items[idx];
   const target = p.type === 'footer' ? section.getFooter(p.headerType || 'Primary') : section.getHeader(p.headerType || 'Primary');
   target.clear();
   target.insertText(p.text, Word.InsertLocation.start);
@@ -715,6 +768,7 @@ commands.setHeaderFooter = (p) => Word.run(async (ctx) => {
 
 // == IMAGES ==
 commands.insertImage = (p) => Word.run(async (ctx) => {
+  if (!p.base64 || typeof p.base64 !== 'string' || p.base64.trim() === '') throw new Error('Invalid image data. Ensure the base64 string is a valid PNG, JPEG, or GIF image.');
   const body = ctx.document.body;
   const picture = body.insertInlinePictureFromBase64(p.base64, p.location || 'End');
   if (p.width) picture.width = p.width;
@@ -757,15 +811,24 @@ 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)');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
+  // Check for existing bookmark with same name
+  const range = ctx.document.body.getRange();
+  const existingBookmarks = range.getBookmarks(true, true);
   await ctx.sync();
+  const isDuplicate = existingBookmarks.value && existingBookmarks.value.includes(p.name);
   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.insertBookmark(p.name);
   target.getRange('End').select();
   await ctx.sync();
-  return { success: true };
+  const result = { success: true };
+  if (isDuplicate) result.warning = 'Bookmark "' + p.name + '" already existed and was moved to the new location.';
+  return result;
 });
 
 commands.deleteBookmark = (p) => Word.run(async (ctx) => {
@@ -805,7 +868,24 @@ commands.getCoauthors = () => Word.run(async (ctx) => {
 commands.saveDocument = () => Word.run(async (ctx) => {
   ctx.document.save();
   await ctx.sync();
-  return { success: true };
+  // Check if document has a file path (has been saved to a location)
+  let path = null;
+  try {
+    const fileProps = await new Promise((resolve) => {
+      Office.context.document.getFilePropertiesAsync(resolve);
+    });
+    if (fileProps.status === Office.AsyncResultStatus.Succeeded && fileProps.value.url) {
+      const url = fileProps.value.url;
+      if (/\.(docx?|docm|dotx?|dotm)$/i.test(url)) {
+        path = url;
+      }
+    }
+  } catch (_e) {}
+  const result = { success: true };
+  if (!path) {
+    result.warning = 'Document has no file path — use Save As in Word to set a location.';
+  }
+  return result;
 });
 
 commands.clearDocument = () => Word.run(async (ctx) => {
@@ -897,6 +977,8 @@ commands.insertSectionBreak = (p) => Word.run(async (ctx) => {
 // == HYPERLINKS ==
 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.');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -952,7 +1034,9 @@ commands.setPageLayout = (p) => Word.run(async (ctx) => {
   const sections = ctx.document.sections;
   sections.load('items');
   await ctx.sync();
-  const section = sections.items[p.sectionIndex || 0];
+  const idx = p.sectionIndex || 0;
+  if (idx < 0 || idx >= sections.items.length) throw new Error('Section index out of range. Document has ' + sections.items.length + ' section(s) (0-indexed).');
+  const section = sections.items[idx];
   const pageSetup = section.pageSetup;
   if (p.orientation) pageSetup.orientation = p.orientation; // 'Portrait' or 'Landscape'
   if (p.topMargin !== undefined) pageSetup.topMargin = p.topMargin;
@@ -968,7 +1052,9 @@ commands.getPageLayout = (p) => Word.run(async (ctx) => {
   const sections = ctx.document.sections;
   sections.load('items');
   await ctx.sync();
-  const section = sections.items[p.sectionIndex || 0];
+  const idx = p.sectionIndex || 0;
+  if (idx < 0 || idx >= sections.items.length) throw new Error('Section index out of range. Document has ' + sections.items.length + ' section(s) (0-indexed).');
+  const section = sections.items[idx];
   const ps = section.pageSetup;
   ps.load('orientation,topMargin,bottomMargin,leftMargin,rightMargin,paperSize,headerDistance,footerDistance');
   await ctx.sync();
@@ -1020,6 +1106,7 @@ commands.deleteCustomProperty = (p) => Word.run(async (ctx) => {
 
 // == ADVANCED TEXT INSERTION ==
 commands.insertHtml = (p) => Word.run(async (ctx) => {
+  if (!p.html || typeof p.html !== 'string' || p.html.trim() === '') throw new Error('html parameter must be a non-empty string');
   const body = ctx.document.body;
   const loc = p.location || 'End';
   const range = body.insertHtml(p.html, loc);
@@ -1095,17 +1182,33 @@ commands.setParagraphSpacing = (p) => Word.run(async (ctx) => {
 
 // == BOOKMARK NAVIGATION ==
 commands.goToBookmark = (p) => Word.run(async (ctx) => {
-  const range = ctx.document.getBookmarkRange(p.name);
-  range.load('text');
-  range.select();
-  await ctx.sync();
+  let range;
+  try {
+    range = ctx.document.getBookmarkRange(p.name);
+    range.load('text');
+    range.select();
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('ItemNotFound')) {
+      throw new Error('Bookmark not found: ' + p.name);
+    }
+    throw e;
+  }
   return { success: true, text: range.text };
 });
 
 commands.getBookmarkText = (p) => Word.run(async (ctx) => {
-  const range = ctx.document.getBookmarkRange(p.name);
-  range.load('text');
-  await ctx.sync();
+  let range;
+  try {
+    range = ctx.document.getBookmarkRange(p.name);
+    range.load('text');
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('ItemNotFound')) {
+      throw new Error('Bookmark not found: ' + p.name);
+    }
+    throw e;
+  }
   return { text: range.text };
 });
 
@@ -1126,14 +1229,25 @@ commands.getSections = () => Word.run(async (ctx) => {
 
 // == TABLE ADVANCED ==
 commands.mergeTableCells = (p) => Word.run(async (ctx) => {
+  if (p.topRow < 0 || p.bottomRow < 0 || p.firstCell < 0 || p.lastCell < 0) throw new Error('All cell indices must be non-negative');
   if (p.topRow > p.bottomRow) throw new Error('topRow (' + p.topRow + ') must be less than or equal to bottomRow (' + p.bottomRow + ')');
   if (p.firstCell > p.lastCell) throw new Error('firstCell (' + p.firstCell + ') must be less than or equal to lastCell (' + p.lastCell + ')');
+  if (p.tableIndex < 0) throw new Error('Table 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');
-  tables.items[p.tableIndex].mergeCells(p.topRow, p.firstCell, p.bottomRow, p.lastCell);
-  await ctx.sync();
+  const table = tables.items[p.tableIndex];
+  if (p.bottomRow >= table.rowCount) throw new Error('bottomRow (' + p.bottomRow + ') exceeds table row count (' + table.rowCount + ')');
+  try {
+    table.mergeCells(p.topRow, p.firstCell, p.bottomRow, p.lastCell);
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('InvalidArgument')) {
+      throw new Error('Cannot merge cells: range is out of bounds. Table has ' + table.rowCount + ' rows. Use word_get_table_data to inspect the table.');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
@@ -1151,12 +1265,20 @@ commands.splitTableCell = (p) => Word.run(async (ctx) => {
 });
 
 commands.setTableStyle = (p) => Word.run(async (ctx) => {
+  if (p.tableIndex < 0) throw new Error('Table 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');
-  tables.items[p.tableIndex].style = p.style;
-  await ctx.sync();
+  try {
+    tables.items[p.tableIndex].style = p.style;
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('InvalidArgument')) {
+      throw new Error('Table style not found: "' + p.style + '". Use a built-in style name like "Grid Table 4 - Accent 1".');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
@@ -1283,6 +1405,7 @@ commands.getImages = () => Word.run(async (ctx) => {
 });
 
 commands.deleteImage = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
   const pics = ctx.document.body.inlinePictures;
   pics.load('altTextDescription');
   await ctx.sync();
@@ -1345,6 +1468,7 @@ commands.removeHyperlink = (p) => Word.run(async (ctx) => {
 
 // == FOOTNOTE/ENDNOTE MANAGEMENT ==
 commands.insertFootnoteAtIndex = (p) => Word.run(async (ctx) => {
+  if (p.paragraphIndex < 0) throw new Error('Index must be non-negative');
   const paragraphs = ctx.document.body.paragraphs;
   paragraphs.load('text');
   await ctx.sync();
@@ -1358,6 +1482,7 @@ commands.insertFootnoteAtIndex = (p) => Word.run(async (ctx) => {
 });
 
 commands.deleteFootnote = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
   const footnotes = ctx.document.body.footnotes;
   footnotes.load('items');
   await ctx.sync();
@@ -1368,6 +1493,7 @@ commands.deleteFootnote = (p) => Word.run(async (ctx) => {
 });
 
 commands.deleteEndnote = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
   const endnotes = ctx.document.body.endnotes;
   endnotes.load('items');
   await ctx.sync();
@@ -1379,6 +1505,7 @@ commands.deleteEndnote = (p) => Word.run(async (ctx) => {
 
 // == LIST OPERATIONS ==
 commands.getListInfo = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
   const paragraphs = ctx.document.body.paragraphs;
   paragraphs.load('text,isListItem');
   await ctx.sync();
@@ -1395,6 +1522,7 @@ commands.getListInfo = (p) => Word.run(async (ctx) => {
 
 commands.setListLevel = (p) => Word.run(async (ctx) => {
   if (p.index < 0) throw new Error('Index must be non-negative');
+  if (p.level < 0 || p.level > 8) throw new Error('level must be between 0 and 8 (inclusive)');
   const paragraphs = ctx.document.body.paragraphs;
   paragraphs.load('text,isListItem');
   await ctx.sync();