mcp-word-bridge 4.0.5 → 4.1.1

package/README.md

@@ -289,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

@@ -18722,7 +18722,15 @@ var Bridge = class {
 
 // src/server/mcp.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
-var import_types7 = require("@modelcontextprotocol/sdk/types.js");
+var import_types8 = require("@modelcontextprotocol/sdk/types.js");
+
+// src/server/types.ts
+var ToolError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ToolError";
+  }
+};
 
 // src/server/tools/helpers.ts
 function jsonResult(data) {
@@ -18823,6 +18831,9 @@ var getDocumentOutline = {
   },
   async handler(args, bridge2) {
     const maxLevel = args.maxLevel ?? 3;
+    if (typeof args.maxLevel === "number" && (args.maxLevel < 1 || args.maxLevel > 9 || !Number.isInteger(args.maxLevel))) {
+      throw new ToolError("maxLevel must be an integer between 1 and 9.");
+    }
     const result = await bridge2.send("getParagraphs", {});
     const headings = [];
     for (const para of result.paragraphs) {
@@ -18854,24 +18865,7 @@ var documentTools = [
   getDocumentOutline
 ];
 
-// src/server/types.ts
-var ToolError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ToolError";
-  }
-};
-
 // 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.`);
@@ -18910,6 +18904,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(
@@ -18972,7 +18984,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)" }
@@ -19027,14 +19039,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);
@@ -19067,7 +19086,7 @@ 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");
@@ -19076,6 +19095,15 @@ var moveParagraph = {
         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 });
@@ -19123,7 +19151,7 @@ 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");
@@ -19155,12 +19183,17 @@ 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. Note: Word search codes (^p = paragraph mark, ^t = tab) are interpreted. To search for literal "^", use "^^".',
+  '[Search] Find text in the document. Returns match count and up to 30 matches. Query must be \u2264255 chars. Supports Word search codes (^p = paragraph mark, ^t = tab, etc.) and wildcard mode (?, *, [], {n,m}). To search for literal "^", use "^^".',
   {
     properties: {
       query: { type: "string" },
       matchCase: { type: "boolean", description: "Case-sensitive search. Default: false" },
-      matchWholeWord: { type: "boolean" }
+      matchWholeWord: { type: "boolean", description: "Match whole words only. Default: false" },
+      matchWildcards: { type: "boolean", description: "Enable wildcard/regex search (?, *, [], {n,m}, @). Default: false" },
+      matchPrefix: { type: "boolean", description: "Match words that begin with the search string. Default: false" },
+      matchSuffix: { type: "boolean", description: "Match words that end with the search string. Default: false" },
+      ignorePunct: { type: "boolean", description: "Ignore punctuation between words when matching. Default: false" },
+      ignoreSpace: { type: "boolean", description: "Ignore whitespace between words when matching. Default: false" }
     },
     required: ["query"]
   },
@@ -19168,38 +19201,46 @@ 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 in both find and replace: ^p (paragraph mark), ^l (line break), ^m (page break), ^n (column break), ^t (tab), ^s (non-breaking space), ^~ (non-breaking hyphen), ^- (optional hyphen), ^+ (em dash), ^= (en dash), ^^ (literal caret). Supports wildcard search in find string. 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", description: "Match whole words only. Default: false" },
+      matchWildcards: { type: "boolean", description: "Enable wildcard/regex search in find string (?, *, [], {n,m}, @). Default: false" },
+      matchPrefix: { type: "boolean", description: "Match words that begin with the find string. Default: false" },
+      matchSuffix: { type: "boolean", description: "Match words that end with the find string. Default: false" },
+      ignorePunct: { type: "boolean", description: "Ignore punctuation between words when matching. Default: false" },
+      ignoreSpace: { type: "boolean", description: "Ignore whitespace between words when matching. Default: false" },
+      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);
   }
 };
 var insertTextAtMatch = forwardTool(
   "word_insert_text_at_match",
-  '[Search] Insert text before or after a search match. Provide "after" OR "before" as the anchor text. Use occurrence for Nth match.',
+  '[Search] Insert text before or after a search match. Supports Word search codes in inserted text: ^p (paragraph mark), ^l (line break), ^t (tab), ^s (non-breaking space), ^m (page break), ^n (column break), ^~ (non-breaking hyphen), ^- (optional hyphen), ^+ (em dash), ^= (en dash), ^^ (literal caret). Provide "after" OR "before" as the anchor text. Use occurrence for Nth match.',
   {
     properties: {
       text: { type: "string", description: "Text to insert" },
       after: { type: "string", description: "Search for this text and insert AFTER it" },
       before: { type: "string", description: "Search for this text and insert BEFORE it" },
       occurrence: { type: "number", description: "0=first, 1=second, etc. Default: 0" },
-      matchCase: { type: "boolean", description: "Default: false" }
+      matchCase: { type: "boolean", description: "Default: false" },
+      matchWildcards: { type: "boolean", description: "Enable wildcard/regex search for anchor text. Default: false" },
+      matchPrefix: { type: "boolean", description: "Match words that begin with the anchor text. Default: false" },
+      matchSuffix: { type: "boolean", description: "Match words that end with the anchor text. Default: false" },
+      ignorePunct: { type: "boolean", description: "Ignore punctuation between words when matching. Default: false" },
+      ignoreSpace: { type: "boolean", description: "Ignore whitespace between words when matching. Default: false" }
     },
     required: ["text"]
   },
@@ -19259,7 +19300,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" }
@@ -19311,7 +19352,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"]
   },
@@ -19790,6 +19831,9 @@ var setContentControlText = {
     if (tag) {
       const ccResult = await bridge2.send("getContentControls", {});
       const matches = ccResult.controls.filter((c) => c.tag === tag);
+      if (matches.length === 0) {
+        throw new ToolError(`Content control with tag "${tag}" not found. Use word_get_content_controls to list available controls.`);
+      }
       if (matches.length > 1) {
         throw new ToolError(
           `Multiple content controls (${matches.length}) share tag "${tag}". Use "id" instead to target a specific control. Matching IDs: ${matches.map((m) => m.id).join(", ")}.`
@@ -20177,6 +20221,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;
@@ -20290,6 +20339,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
 
@@ -20400,7 +20463,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.5",
+  version: "4.1.1",
   description: "MCP server for live Word document editing via Office Add-in",
   main: "dist/server.js",
   bin: {
@@ -20464,7 +20527,8 @@ function createMcpServer(bridge2) {
     { capabilities: { tools: {}, resources: {} } }
   );
   const { tools, handlers } = buildToolRegistry();
-  server.setRequestHandler(import_types7.ListToolsRequestSchema, async () => ({
+  const toolMutex = createMutex();
+  server.setRequestHandler(import_types8.ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
@@ -20475,21 +20539,23 @@ 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 };
-    }
+  server.setRequestHandler(import_types8.CallToolRequestSchema, async (request) => {
+    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 () => ({
+  server.setRequestHandler(import_types8.ListResourcesRequestSchema, async () => ({
     resources: [{
       uri: "word-bridge://usage-guide",
       name: "Word Bridge Usage Guide",
@@ -20497,7 +20563,7 @@ function createMcpServer(bridge2) {
       mimeType: "text/markdown"
     }]
   }));
-  server.setRequestHandler(import_types7.ReadResourceRequestSchema, async (request) => {
+  server.setRequestHandler(import_types8.ReadResourceRequestSchema, async (request) => {
     if (request.params.uri === "word-bridge://usage-guide") {
       return { contents: [{ uri: request.params.uri, mimeType: "text/markdown", text: usageGuide }] };
     }