mcp-word-bridge 4.0.4 → 4.1.0

package/README.md

@@ -70,7 +70,6 @@ Single process. The MCP client spawns the server, which starts both the HTTPS br
 | `word_set_document_properties` | Set metadata fields |
 | `word_save` | Save document to disk |
 | `word_clear` | Clear all document body content |
-| `word_create_document` | Create and open a new blank document in a new Word window |
 | `word_get_word_count` | Get word, character, and paragraph counts |
 | `word_get_styles` | List available styles |
 | `word_get_coauthors` | Get co-authoring status and active authors |
@@ -290,6 +289,19 @@ src/
     └── equations.ts  # LaTeX→OMML conversion pipeline
 ```
 
+## Known Limitations
+
+Platform constraints in the Word JavaScript API that cannot be resolved in this project:
+
+| Area | Limitation | Upstream Issue |
+|------|------------|----------------|
+| Tracked Changes | `word_get_tracked_changes` returns empty `text` for deletions. The `Word.TrackedChange.text` property returns `""` when `type` is `"Deleted"`. Only additions and formatting changes include text content. | [office-js#5188](https://github.com/OfficeDev/office-js/issues/5188) |
+| Tracked Changes | `getTrackedChanges()` throws if the document contains "moved" tracked changes (drag-and-drop reorders). These produce paired "moved from"/"moved to" entries that the API cannot handle. | [office-js#5535](https://github.com/OfficeDev/office-js/issues/5535) |
+| Highlight Colors | `highlightColor` only supports 17 named colors (Yellow, Green, Cyan, Magenta, Blue, Red, DarkBlue, DarkCyan, DarkGreen, DarkMagenta, DarkRed, DarkYellow, Gray25, Gray50, Black, White, NoHighlight). The Word API documentation claims `#RRGGBB` is accepted, but Desktop silently maps hex values to the nearest named color. This tool rejects hex to prevent silent mismatch — use `color` for arbitrary RGB. | [office-js#4638](https://github.com/OfficeDev/office-js/issues/4638) |
+| Paragraph Style | TOC field entries and certain table paragraphs return `style: ""` (empty string) instead of the actual style name. Paragraphs are flagged with `isTocEntry: true` when detected as TOC entries. Use this flag rather than the style field for identification. | [office-js#5934](https://github.com/OfficeDev/office-js/issues/5934) |
+| Page Info | `word_get_page_info` requires WordApiDesktop 1.2+ (Word for Windows/Mac desktop). Not available on Word for the web. |  |
+| Undo | The Word JavaScript API does not expose a programmatic `undo()` method. Changes made by the add-in appear in Word's undo stack (Ctrl+Z works for the user), but there is no way to trigger undo from code. |  |
+
 ## License
 
 MIT

package/dist/server.js

@@ -18784,16 +18784,6 @@ var clear = forwardTool(
   { properties: {} },
   "clearDocument"
 );
-var createDocument = forwardTool(
-  "word_create_document",
-  "[Document] Create and open a new blank document in a new Word window. Optionally provide base64-encoded .docx as template.",
-  {
-    properties: {
-      base64: { type: "string", description: "Optional base64-encoded .docx file to use as template" }
-    }
-  },
-  "createNewDocument"
-);
 var getWordCount = forwardTool(
   "word_get_word_count",
   "[Document] Get word, character, and paragraph counts.",
@@ -18857,7 +18847,6 @@ var documentTools = [
   setDocumentProperties,
   save,
   clear,
-  createDocument,
   getWordCount,
   getStyles,
   getCoauthors,
@@ -18874,15 +18863,6 @@ var ToolError = class extends Error {
 };
 
 // src/server/validation.ts
-var WORD_SPECIAL_CODES = /\^(p|w|t|l|m|b|n|s|d|a|e|f|g|v|~|\^|\-|13|11|14|12|07|09|30|31|32|34|36|37|38|39|40|41|42|43|44|45|46|47|92|94|127|129|130|131|132|133|134|135|136|137|138|139|140|141|142|143|144|145|146|147|148|149|150|151|152|153|154|155|156|157|158|159|160|161|162|163|164|165|166|167|168|169|170|171|172|173|174|175|176|177|178|179|180|181|182|183|184|185|186|187|188|189|190|191|192|193|194|195|196|197|198|199|200|201|202|203|204|205|206|207|208|209|210|211|212|213|214|215|216|217|218|219|220|221|222|223|224|225|226|227|228|229|230|231|232|233|234|235|236|237|238|239|240|241|242|243|244|245|246|247|248|249|250|251|252|253|254|255)/;
-function checkNoSpecialCodes(text2, paramName) {
-  const match = text2.match(WORD_SPECIAL_CODES);
-  if (match) {
-    throw new ToolError(
-      `${paramName} contains Word special code "${match[0]}" which can corrupt document structure. Use literal text only. Common special codes: ^p (paragraph mark), ^t (tab), ^w (whitespace), ^13 (paragraph mark).`
-    );
-  }
-}
 function checkNonEmpty(value, name) {
   if (!value || typeof value !== "string" || value.trim() === "") {
     throw new ToolError(`${name} must be a non-empty string.`);
@@ -18921,6 +18901,24 @@ function checkSpacingBounds(value, name) {
     );
   }
 }
+function checkIndentBounds(value, name) {
+  if (name === "firstLineIndent") {
+    if (value < -MAX_SPACING_POINTS || value > MAX_SPACING_POINTS) {
+      throw new ToolError(
+        `${name} value ${value} is out of range. Valid range: -${MAX_SPACING_POINTS} to ${MAX_SPACING_POINTS} points.`
+      );
+    }
+  } else {
+    if (value < 0) {
+      throw new ToolError(`${name} must be non-negative (in points).`);
+    }
+    if (value > MAX_SPACING_POINTS) {
+      throw new ToolError(
+        `${name} value ${value} exceeds maximum (${MAX_SPACING_POINTS} points = 22 inches).`
+      );
+    }
+  }
+}
 function checkPropertyKeyLength(key) {
   if (key.length > MAX_CUSTOM_PROPERTY_KEY_LENGTH) {
     throw new ToolError(
@@ -18983,7 +18981,7 @@ var insertParagraphAtIndex = forwardTool(
 );
 var deleteParagraph = forwardTool(
   "word_delete_paragraph",
-  "[Paragraphs] Delete a paragraph by its 0-based index.",
+  "[Paragraphs] Delete a paragraph by its 0-based index. For table cells with multiple paragraphs, extra paragraphs can be removed (the last paragraph in a cell cannot be deleted).",
   {
     properties: {
       index: { type: "number", description: "Paragraph index (0-based)" }
@@ -19038,14 +19036,21 @@ var setParagraphSpacing = {
     const spacingFields = [
       ["lineSpacing", args.lineSpacing],
       ["spaceBefore", args.spaceBefore],
-      ["spaceAfter", args.spaceAfter],
+      ["spaceAfter", args.spaceAfter]
+    ];
+    for (const [name, value] of spacingFields) {
+      if (value !== void 0 && typeof value === "number") {
+        checkSpacingBounds(value, name);
+      }
+    }
+    const indentFields = [
       ["firstLineIndent", args.firstLineIndent],
       ["leftIndent", args.leftIndent],
       ["rightIndent", args.rightIndent]
     ];
-    for (const [name, value] of spacingFields) {
+    for (const [name, value] of indentFields) {
       if (value !== void 0 && typeof value === "number") {
-        checkSpacingBounds(value, name);
+        checkIndentBounds(value, name);
       }
     }
     const result = await bridge2.send("setParagraphSpacing", args);
@@ -19078,16 +19083,36 @@ var moveParagraph = {
       throw new ToolError(`toIndex (${toIndex}) is inside the source range [${fromIndex}, ${fromIndex + count - 1}]. Move to a position outside the range.`);
     }
     const paraCount = await bridge2.send("getParagraphs", {});
-    const total = paraCount.count;
+    const total = paraCount.total;
     checkBounds(fromIndex, total, "fromIndex");
     if (fromIndex + count - 1 >= total) throw new ToolError(`fromIndex + count (${fromIndex + count}) exceeds paragraph count (${total}).`);
     checkBounds(toIndex, total, "toIndex");
+    for (const para of paraCount.paragraphs) {
+      if (para.index >= fromIndex && para.index < fromIndex + count && para.inTable) {
+        throw new ToolError(`Paragraph ${para.index} is inside a table cell. Use table-specific tools to modify table content.`);
+      }
+    }
+    const lastIdx = total - 1;
+    if (fromIndex + count - 1 === lastIdx) {
+      const lastPara = paraCount.paragraphs.find((p) => p.index === lastIdx);
+      if (lastPara && lastPara.text === "") {
+        throw new ToolError(
+          `Cannot move the last paragraph (index ${lastIdx}) \u2014 Word requires at least one paragraph and will auto-create a replacement, resulting in duplication. Use word_copy_paragraph instead, or exclude the trailing paragraph from the range.`
+        );
+      }
+    }
+    const adjustedTo = fromIndex < toIndex ? toIndex - count : toIndex;
+    if (toIndex === fromIndex + count && location === "After") {
+      return jsonResult({ success: true, warning: "No move performed \u2014 destination is equivalent to source position.", moved: null });
+    }
+    if (adjustedTo === fromIndex && location === "After") {
+      return jsonResult({ success: true, warning: "No move performed \u2014 destination is equivalent to source position.", moved: null });
+    }
     const ooxmlResult = await bridge2.send("getParaOoxml", { index: fromIndex, count });
     const savedOoxml = ooxmlResult.ooxml;
     for (let i = count - 1; i >= 0; i--) {
       await bridge2.send("deleteParagraph", { index: fromIndex + i });
     }
-    const adjustedTo = fromIndex < toIndex ? toIndex - count : toIndex;
     try {
       await bridge2.send("insertOoxmlAtIndex", { ooxml: savedOoxml, index: adjustedTo, location });
     } catch (insertErr) {
@@ -19123,12 +19148,19 @@ var copyParagraph = {
     if (!Number.isInteger(count)) throw new ToolError("count must be an integer.");
     if (count < 1) throw new ToolError("count must be at least 1");
     const paraCount = await bridge2.send("getParagraphs", {});
-    const total = paraCount.count;
+    const total = paraCount.total;
     checkBounds(fromIndex, total, "fromIndex");
     if (fromIndex + count - 1 >= total) throw new ToolError(`fromIndex + count (${fromIndex + count}) exceeds paragraph count (${total}).`);
     checkBounds(toIndex, total, "toIndex");
+    for (const para of paraCount.paragraphs) {
+      if (para.index >= fromIndex && para.index < fromIndex + count && para.inTable) {
+        throw new ToolError(`Paragraph ${para.index} is inside a table cell. Use table-specific tools to modify table content.`);
+      }
+    }
     const ooxmlResult = await bridge2.send("getParaOoxml", { index: fromIndex, count });
-    await bridge2.send("insertOoxmlAtIndex", { ooxml: ooxmlResult.ooxml, index: toIndex, location });
+    const effectiveToIndex = toIndex >= fromIndex && toIndex < fromIndex + count ? fromIndex + count - 1 : toIndex;
+    const effectiveLocation = toIndex >= fromIndex && toIndex < fromIndex + count ? "After" : location;
+    await bridge2.send("insertOoxmlAtIndex", { ooxml: ooxmlResult.ooxml, index: effectiveToIndex, location: effectiveLocation });
     return jsonResult({ success: true, copied: { from: fromIndex, count, to: toIndex, location } });
   }
 };
@@ -19148,7 +19180,7 @@ var paragraphTools = [
 // src/server/tools/search.ts
 var search = forwardTool(
   "word_search",
-  "[Search] Find text in the document. Returns match count and up to 30 matches. Query must be \u2264255 chars.",
+  '[Search] Find text in the document. Returns match count and up to 30 matches. Query must be \u2264255 chars. Note: Word search codes (^p = paragraph mark, ^t = tab) are interpreted. To search for literal "^", use "^^".',
   {
     properties: {
       query: { type: "string" },
@@ -19161,24 +19193,22 @@ var search = forwardTool(
 );
 var searchAndReplace = {
   name: "word_search_and_replace",
-  description: "[Search] Find and replace ALL occurrences. For single-paragraph edits, prefer word_replace_paragraph_text.",
+  description: "[Search] Find and replace ALL occurrences. Supports Word search codes (^p = paragraph mark, ^t = tab). For single-paragraph edits, prefer word_replace_paragraph_text.",
   schema: {
     properties: {
       find: { type: "string" },
       replace: { type: "string" },
       matchCase: { type: "boolean", description: "Default: false" },
-      matchWholeWord: { type: "boolean" }
+      matchWholeWord: { type: "boolean" },
+      preserveBookmarks: { type: "boolean", description: "Re-create bookmarks on replacement text after replace. Default: false" }
     },
     required: ["find", "replace"]
   },
   async handler(args, bridge2) {
     const find = args.find;
-    const replace = args.replace;
     if (!find || typeof find !== "string" || find.trim() === "") {
       throw new ToolError("find string cannot be empty.");
     }
-    checkNoSpecialCodes(find, "find");
-    checkNoSpecialCodes(replace, "replace");
     const result = await bridge2.send("searchAndReplace", args);
     return jsonResult(result);
   }
@@ -19252,7 +19282,7 @@ var formatText = forwardTool(
       underline: { type: "boolean" },
       strikeThrough: { type: "boolean" },
       color: { type: "string", description: "Hex color e.g. #FF0000" },
-      highlightColor: { type: "string", description: "Highlight color name or hex" },
+      highlightColor: { type: "string", description: "Highlight color name (Yellow, Green, Cyan, Magenta, Blue, Red, DarkBlue, DarkCyan, DarkGreen, DarkMagenta, DarkRed, DarkYellow, Gray25, Gray50, Black, White, NoHighlight)" },
       size: { type: "number", description: "Font size in points (1-1638)" },
       name: { type: "string", description: "Font name" },
       matchCase: { type: "boolean", description: "Default: false" }
@@ -19304,7 +19334,7 @@ var insertTable = forwardTool(
       data: { type: "array", items: { type: "array", items: { type: "string" } }, description: "Cell values as array of row arrays" },
       location: { type: "string", enum: ["Start", "End"] },
       style: { type: "string", description: "Table style name" },
-      headerRowCount: { type: "number" }
+      headerRowCount: { type: "number", description: "Number of header rows (default: 0). Set to 1 to mark the first row as a repeating header." }
     },
     required: ["rows", "cols"]
   },
@@ -19556,7 +19586,7 @@ var commentTools = [
 // src/server/tools/footnotes.ts
 var insertFootnote = forwardTool(
   "word_insert_footnote",
-  "[Footnotes] Insert a footnote anchored to a text match.",
+  "[Footnotes] Insert a footnote anchored to a text match. Note: multiple footnotes on the same anchor appear in reverse insertion order (most recent first). Use word_insert_footnote_at_index for explicit placement.",
   {
     properties: {
       anchorText: { type: "string", description: "Text to search for as anchor point" },
@@ -20170,6 +20200,11 @@ function createBatchTool(registry, actionMap) {
       if (operations.length > MAX_BATCH_OPERATIONS) {
         throw new ToolError(`maximum ${MAX_BATCH_OPERATIONS} operations per batch`);
       }
+      for (const op of operations) {
+        if (op.tool === "word_batch") {
+          throw new ToolError("word_batch cannot be nested inside another batch. Flatten your operations into a single batch call.");
+        }
+      }
       const results = [];
       let nativeBuf = [];
       let stopped = false;
@@ -20283,6 +20318,20 @@ function buildToolRegistry() {
   return { tools: allTools, handlers };
 }
 
+// src/server/mutex.ts
+function createMutex() {
+  let chain = Promise.resolve();
+  return {
+    run(fn) {
+      const next = chain.then(fn, fn);
+      chain = next.then(noop, noop);
+      return next;
+    }
+  };
+}
+function noop() {
+}
+
 // src/server/usage-guide.ts
 var usageGuide = `# MCP Word Bridge \u2014 Usage Guide
 
@@ -20393,7 +20442,7 @@ After inserting a Table of Contents, heading text appears twice (in TOC and body
 // package.json
 var package_default = {
   name: "mcp-word-bridge",
-  version: "4.0.4",
+  version: "4.1.0",
   description: "MCP server for live Word document editing via Office Add-in",
   main: "dist/server.js",
   bin: {
@@ -20457,6 +20506,7 @@ function createMcpServer(bridge2) {
     { capabilities: { tools: {}, resources: {} } }
   );
   const { tools, handlers } = buildToolRegistry();
+  const toolMutex = createMutex();
   server.setRequestHandler(import_types7.ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.name,
@@ -20469,18 +20519,20 @@ function createMcpServer(bridge2) {
     }))
   }));
   server.setRequestHandler(import_types7.CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    const handler = handlers.get(name);
-    if (!handler) {
-      return { content: [{ type: "text", text: "Unknown tool: " + name }], isError: true };
-    }
-    try {
-      const result = await handler(args || {}, bridge2);
-      return result;
-    } catch (e) {
-      const msg = e instanceof ToolError ? e.message : "Error: " + e.message;
-      return { content: [{ type: "text", text: msg }], isError: true };
-    }
+    return toolMutex.run(async () => {
+      const { name, arguments: args } = request.params;
+      const handler = handlers.get(name);
+      if (!handler) {
+        return { content: [{ type: "text", text: "Unknown tool: " + name }], isError: true };
+      }
+      try {
+        const result = await handler(args || {}, bridge2);
+        return result;
+      } catch (e) {
+        const msg = e instanceof ToolError ? e.message : "Error: " + e.message;
+        return { content: [{ type: "text", text: msg }], isError: true };
+      }
+    });
   });
   server.setRequestHandler(import_types7.ListResourcesRequestSchema, async () => ({
     resources: [{