mcp-word-bridge 4.1.0 → 4.1.2

package/README.md

@@ -266,7 +266,7 @@ npm install
 npm run build        # build server + taskpane
 npm run dev          # watch mode
 npm run typecheck    # TypeScript type checking
-npm test             # unit tests (67 tests, <500ms)
+npm test             # unit tests (272 tests, <600ms)
 npm run test:live    # integration tests (requires Word)
 ```
 
@@ -299,8 +299,9 @@ Platform constraints in the Word JavaScript API that cannot be resolved in this
 | 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. |  |
+| Mixed Formatting | `word_get_paragraph_by_index` returns `null` for font properties (`bold`, `italic`, `size`, etc.) when the paragraph contains mixed formatting (e.g. partially bold text). This is the Word API's way of indicating "no single value" — treat `null` as "mixed". | [Word.Font docs](https://learn.microsoft.com/en-us/javascript/api/word/word.font?view=word-js-preview) |
+| Page Info | `word_get_page_info` requires WordApiDesktop 1.2+ (Word for Windows/Mac desktop). Not available on Word for the web. | [WordApiDesktop 1.2](https://learn.microsoft.com/en-us/javascript/api/requirement-sets/word/word-api-desktop-1-2-requirement-set) |
+| 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. | [Stack Overflow](https://stackoverflow.com/questions/58440921/accessing-the-undo-stack-from-word-javascript-api) |
 
 ## License
 

package/dist/server.js

@@ -18722,19 +18722,28 @@ 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_types9 = 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) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
-function forwardTool(name, description, schema, action) {
+function forwardTool(name, description, schema, action, validate) {
   return {
     name,
     description,
     schema,
     bridgeAction: action,
     async handler(args, bridge2) {
+      if (validate) validate(args);
       const result = await bridge2.send(action, args);
       return jsonResult(result);
     }
@@ -18780,7 +18789,7 @@ var save = forwardTool(
 );
 var clear = forwardTool(
   "word_clear",
-  "[Document] Clear all document body content. Does not clear headers/footers or custom properties.",
+  "[Document] Clear all document body content. Does not clear headers/footers or custom properties. In multi-section documents, section breaks are removed and the last section's layout (margins, orientation) is preserved.",
   { properties: {} },
   "clearDocument"
 );
@@ -18823,6 +18832,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,14 +18866,6 @@ var documentTools = [
   getDocumentOutline
 ];
 
-// src/server/types.ts
-var ToolError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ToolError";
-  }
-};
-
 // src/server/validation.ts
 function checkNonEmpty(value, name) {
   if (!value || typeof value !== "string" || value.trim() === "") {
@@ -18926,6 +18930,11 @@ function checkPropertyKeyLength(key) {
     );
   }
 }
+function checkHexColor(color, name) {
+  if (!/^#[0-9A-Fa-f]{6}$/.test(color)) {
+    throw new ToolError(`${name} must be a valid hex color (e.g. #FF0000).`);
+  }
+}
 
 // src/server/tools/paragraphs.ts
 var getParagraphs = forwardTool(
@@ -18941,7 +18950,7 @@ var getParagraphs = forwardTool(
 );
 var getParagraphByIndex = forwardTool(
   "word_get_paragraph_by_index",
-  "[Paragraphs] Get full details of a single paragraph including font, spacing, indentation, and outline level.",
+  "[Paragraphs] Get full details of a single paragraph including font, spacing, indentation, and outline level. Font properties return null when the paragraph has mixed formatting (e.g. partially bold).",
   {
     properties: {
       index: { type: "number", description: "Paragraph index (0-based)" }
@@ -19033,6 +19042,12 @@ var setParagraphSpacing = {
   async handler(args, bridge2) {
     const index = args.index;
     checkNonNegative(index, "index");
+    const hasProperty = args.lineSpacing !== void 0 || args.spaceBefore !== void 0 || args.spaceAfter !== void 0 || args.firstLineIndent !== void 0 || args.leftIndent !== void 0 || args.rightIndent !== void 0;
+    if (!hasProperty) {
+      throw new ToolError(
+        "At least one spacing or indent property must be provided (lineSpacing, spaceBefore, spaceAfter, firstLineIndent, leftIndent, rightIndent)."
+      );
+    }
     const spacingFields = [
       ["lineSpacing", args.lineSpacing],
       ["spaceBefore", args.spaceBefore],
@@ -19092,6 +19107,12 @@ var moveParagraph = {
         throw new ToolError(`Paragraph ${para.index} is inside a table cell. Use table-specific tools to modify table content.`);
       }
     }
+    const destPara = paraCount.paragraphs.find((p) => p.index === toIndex);
+    if (destPara?.inTable) {
+      throw new ToolError(
+        `Destination paragraph ${toIndex} is inside a table cell. Moving content here would corrupt table structure. Use table-specific tools or target a paragraph outside the table.`
+      );
+    }
     const lastIdx = total - 1;
     if (fromIndex + count - 1 === lastIdx) {
       const lastPara = paraCount.paragraphs.find((p) => p.index === lastIdx);
@@ -19157,6 +19178,12 @@ var copyParagraph = {
         throw new ToolError(`Paragraph ${para.index} is inside a table cell. Use table-specific tools to modify table content.`);
       }
     }
+    const destPara = paraCount.paragraphs.find((p) => p.index === toIndex);
+    if (destPara?.inTable) {
+      throw new ToolError(
+        `Destination paragraph ${toIndex} is inside a table cell. Copying content here would corrupt table structure. Use table-specific tools or target a paragraph outside the table.`
+      );
+    }
     const ooxmlResult = await bridge2.send("getParaOoxml", { index: fromIndex, count });
     const effectiveToIndex = toIndex >= fromIndex && toIndex < fromIndex + count ? fromIndex + count - 1 : toIndex;
     const effectiveLocation = toIndex >= fromIndex && toIndex < fromIndex + count ? "After" : location;
@@ -19180,12 +19207,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"]
   },
@@ -19193,13 +19225,18 @@ var search = forwardTool(
 );
 var searchAndReplace = {
   name: "word_search_and_replace",
-  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.",
+  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"]
@@ -19215,14 +19252,19 @@ var searchAndReplace = {
 };
 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. Note: inserting ^p after hyperlinked text may create a paragraph that inherits the hyperlink character style.',
   {
     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"]
   },
@@ -19270,6 +19312,34 @@ var searchTools = [
 ];
 
 // src/server/tools/formatting.ts
+var HIGHLIGHT_COLORS = ["Yellow", "Green", "Cyan", "Magenta", "Blue", "Red", "DarkBlue", "DarkCyan", "DarkGreen", "DarkMagenta", "DarkRed", "DarkYellow", "Gray25", "Gray50", "Black", "White", "NoHighlight"];
+function validateFormatText(args) {
+  checkNonEmpty(args.text, "text");
+  const hasFormatting = args.bold !== void 0 || args.italic !== void 0 || args.underline !== void 0 || args.strikeThrough !== void 0 || args.color !== void 0 || args.highlightColor !== void 0 || args.size !== void 0 || args.name !== void 0;
+  if (!hasFormatting) {
+    throw new ToolError(
+      "At least one formatting property must be specified (bold, italic, underline, strikeThrough, color, highlightColor, size, or name)."
+    );
+  }
+  if (args.size !== void 0) {
+    const size = args.size;
+    if (size <= 0) throw new ToolError("size must be positive (minimum 1 point).");
+    if (size > 1638) throw new ToolError("size must not exceed 1638 points (Word maximum).");
+    if (!Number.isFinite(size)) throw new ToolError("size must be a finite number.");
+  }
+  if (args.color !== void 0) {
+    checkHexColor(args.color, "color");
+  }
+  if (args.highlightColor !== void 0) {
+    const hc = args.highlightColor;
+    const isNamed = HIGHLIGHT_COLORS.some((c) => c.toLowerCase() === hc.toLowerCase());
+    if (!isNamed) {
+      throw new ToolError(
+        `Invalid highlightColor: "${hc}". Valid values: ${HIGHLIGHT_COLORS.join(", ")}.`
+      );
+    }
+  }
+}
 var formatText = forwardTool(
   "word_format_text",
   "[Formatting] Apply formatting (bold, italic, color, size, font) to a text match. Color must be hex (#FF0000). Size: 1-1638pt.",
@@ -19289,7 +19359,8 @@ var formatText = forwardTool(
     },
     required: ["text"]
   },
-  "formatRange"
+  "formatRange",
+  validateFormatText
 );
 var clearFormatting = forwardTool(
   "word_clear_formatting",
@@ -19468,7 +19539,7 @@ var tableTools = [
 // src/server/tools/lists.ts
 var insertList = forwardTool(
   "word_insert_list",
-  "[Lists] Insert a bulleted or numbered list from an array of item strings.",
+  "[Lists] Insert a bulleted or numbered list from an array of item strings. Text is inserted literally (Word search codes like ^p or ^t are NOT interpreted).",
   {
     properties: {
       items: { type: "array", items: { type: "string" }, description: "List item strings" },
@@ -19521,7 +19592,11 @@ var addComment = forwardTool(
     },
     required: ["anchorText", "comment"]
   },
-  "addComment"
+  "addComment",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+    checkNonEmpty(args.comment, "comment");
+  }
 );
 var getComments = forwardTool(
   "word_get_comments",
@@ -19550,7 +19625,10 @@ var replyToComment = forwardTool(
     },
     required: ["commentId", "text"]
   },
-  "replyToComment"
+  "replyToComment",
+  (args) => {
+    checkNonEmpty(args.text, "text");
+  }
 );
 var resolveComment = forwardTool(
   "word_resolve_comment",
@@ -19813,6 +19891,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(", ")}.`
@@ -20181,7 +20262,7 @@ var equationTools = [
 function createBatchTool(registry, actionMap) {
   return {
     name: "word_batch",
-    description: "[Batch] Execute multiple operations in a single call. Operations execute sequentially \u2014 if one fails, subsequent are skipped.",
+    description: "[Batch] Execute multiple operations in a single call. Operations execute sequentially \u2014 if one fails, subsequent are skipped. Note: paragraph indices are NOT auto-adjusted between operations. Multiple inserts at the same index will produce reversed order (last inserted appears first).",
     schema: {
       properties: {
         operations: {
@@ -20377,6 +20458,8 @@ Controls a live Word document. All operations execute immediately.
 \`\`\`
 Runs sequentially. Stops on first error. Maximum 50 per batch. Prefer batching over individual calls.
 
+**Index caveat:** Paragraph indices are NOT auto-adjusted between operations. Multiple inserts at the same index produce reversed order (last inserted appears first). To insert A, B, C in order at position 5, either increment the index or insert in reverse.
+
 ## Search
 
 - Case-insensitive by default. Pass \`matchCase: true\` for exact case.
@@ -20437,12 +20520,21 @@ After inserting a Table of Contents, heading text appears twice (in TOC and body
 6. Use \`word_copy_paragraph\` to duplicate (preserves everything)
 7. Save explicitly after significant changes
 8. Resolve comments rather than deleting (preserves audit trail)
+
+## Alignment Values
+
+Input accepts case-insensitive: "left", "center", "right", "justified".
+Output always uses canonical form: "Left", "Center", "Right", "Justified".
+
+## Mixed Formatting
+
+\`word_get_paragraph_by_index\` returns \`null\` for font properties when the paragraph has mixed formatting (e.g. partially bold). Treat \`null\` as "mixed" \u2014 use \`word_get_font_info\` with a specific text match for precise values.
 `;
 
 // package.json
 var package_default = {
   name: "mcp-word-bridge",
-  version: "4.1.0",
+  version: "4.1.2",
   description: "MCP server for live Word document editing via Office Add-in",
   main: "dist/server.js",
   bin: {
@@ -20507,7 +20599,7 @@ function createMcpServer(bridge2) {
   );
   const { tools, handlers } = buildToolRegistry();
   const toolMutex = createMutex();
-  server.setRequestHandler(import_types7.ListToolsRequestSchema, async () => ({
+  server.setRequestHandler(import_types9.ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
@@ -20518,7 +20610,7 @@ function createMcpServer(bridge2) {
       }
     }))
   }));
-  server.setRequestHandler(import_types7.CallToolRequestSchema, async (request) => {
+  server.setRequestHandler(import_types9.CallToolRequestSchema, async (request) => {
     return toolMutex.run(async () => {
       const { name, arguments: args } = request.params;
       const handler = handlers.get(name);
@@ -20534,7 +20626,7 @@ function createMcpServer(bridge2) {
       }
     });
   });
-  server.setRequestHandler(import_types7.ListResourcesRequestSchema, async () => ({
+  server.setRequestHandler(import_types9.ListResourcesRequestSchema, async () => ({
     resources: [{
       uri: "word-bridge://usage-guide",
       name: "Word Bridge Usage Guide",
@@ -20542,7 +20634,7 @@ function createMcpServer(bridge2) {
       mimeType: "text/markdown"
     }]
   }));
-  server.setRequestHandler(import_types7.ReadResourceRequestSchema, async (request) => {
+  server.setRequestHandler(import_types9.ReadResourceRequestSchema, async (request) => {
     if (request.params.uri === "word-bridge://usage-guide") {
       return { contents: [{ uri: request.params.uri, mimeType: "text/markdown", text: usageGuide }] };
     }