mcp-word-bridge 4.1.1 → 4.1.3

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,10 @@ 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) |
+| TOC Search | `body.search()` matches text inside TOC field entries as well as body content. Heading text appears in both locations, so search results return TOC matches first. Use `occurrence` to skip past TOC entries and target the body instance. |  |
+| 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

@@ -18646,6 +18646,7 @@ var HEAVY_OPERATIONS = /* @__PURE__ */ new Set([
   "batchExecute"
 ]);
 var MAX_PAYLOAD = 10 * 1024 * 1024;
+var HIGHLIGHT_COLORS = ["Yellow", "Green", "Cyan", "Magenta", "Blue", "Red", "DarkBlue", "DarkCyan", "DarkGreen", "DarkMagenta", "DarkRed", "DarkYellow", "Gray25", "Gray50", "Black", "White", "NoHighlight"];
 
 // src/server/bridge.ts
 var Bridge = class {
@@ -18722,7 +18723,7 @@ var Bridge = class {
 
 // src/server/mcp.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
-var import_types8 = require("@modelcontextprotocol/sdk/types.js");
+var import_types9 = require("@modelcontextprotocol/sdk/types.js");
 
 // src/server/types.ts
 var ToolError = class extends Error {
@@ -18736,13 +18737,15 @@ var ToolError = class extends Error {
 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,
+    validate,
     async handler(args, bridge2) {
+      if (validate) validate(args);
       const result = await bridge2.send(action, args);
       return jsonResult(result);
     }
@@ -18788,7 +18791,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"
 );
@@ -18929,6 +18932,19 @@ 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).`);
+  }
+}
+function checkUrl(url) {
+  if (!/^https?:\/\/.+/i.test(url)) {
+    throw new ToolError("URL must be a valid HTTP or HTTPS URL (e.g. https://example.com).");
+  }
+  if (/[<>"{}|\\^`]/.test(url)) {
+    throw new ToolError(`Malformed URL: "${url}". URL contains invalid characters that must be percent-encoded.`);
+  }
+}
 
 // src/server/tools/paragraphs.ts
 var getParagraphs = forwardTool(
@@ -18944,7 +18960,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)" }
@@ -19036,6 +19052,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],
@@ -19095,6 +19117,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);
@@ -19105,10 +19133,8 @@ var moveParagraph = {
       }
     }
     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") {
+    const effectiveInsertPos = location === "Before" ? adjustedTo : adjustedTo + 1;
+    if (effectiveInsertPos === fromIndex) {
       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 });
@@ -19160,6 +19186,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;
@@ -19197,7 +19229,10 @@ var search = forwardTool(
     },
     required: ["query"]
   },
-  "search"
+  "search",
+  (args) => {
+    checkNonEmpty(args.query, "query");
+  }
 );
 var searchAndReplace = {
   name: "word_search_and_replace",
@@ -19228,7 +19263,7 @@ var searchAndReplace = {
 };
 var insertTextAtMatch = forwardTool(
   "word_insert_text_at_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.',
+  '[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" },
@@ -19276,7 +19311,10 @@ var insertLineBreak = forwardTool(
     },
     required: ["anchorText"]
   },
-  "insertLineBreak"
+  "insertLineBreak",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+  }
 );
 var searchTools = [
   search,
@@ -19288,6 +19326,33 @@ var searchTools = [
 ];
 
 // src/server/tools/formatting.ts
+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.",
@@ -19307,7 +19372,8 @@ var formatText = forwardTool(
     },
     required: ["text"]
   },
-  "formatRange"
+  "formatRange",
+  validateFormatText
 );
 var clearFormatting = forwardTool(
   "word_clear_formatting",
@@ -19486,7 +19552,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" },
@@ -19539,7 +19605,11 @@ var addComment = forwardTool(
     },
     required: ["anchorText", "comment"]
   },
-  "addComment"
+  "addComment",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+    checkNonEmpty(args.comment, "comment");
+  }
 );
 var getComments = forwardTool(
   "word_get_comments",
@@ -19568,7 +19638,10 @@ var replyToComment = forwardTool(
     },
     required: ["commentId", "text"]
   },
-  "replyToComment"
+  "replyToComment",
+  (args) => {
+    checkNonEmpty(args.text, "text");
+  }
 );
 var resolveComment = forwardTool(
   "word_resolve_comment",
@@ -19614,7 +19687,11 @@ var insertFootnote = forwardTool(
     },
     required: ["anchorText", "text"]
   },
-  "insertFootnote"
+  "insertFootnote",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+    checkNonEmpty(args.text, "text");
+  }
 );
 var insertFootnoteAtIndex = forwardTool(
   "word_insert_footnote_at_index",
@@ -19626,7 +19703,10 @@ var insertFootnoteAtIndex = forwardTool(
     },
     required: ["paragraphIndex", "text"]
   },
-  "insertFootnoteAtIndex"
+  "insertFootnoteAtIndex",
+  (args) => {
+    checkNonEmpty(args.text, "text");
+  }
 );
 var insertEndnote = forwardTool(
   "word_insert_endnote",
@@ -19640,7 +19720,11 @@ var insertEndnote = forwardTool(
     },
     required: ["anchorText", "text"]
   },
-  "insertEndnote"
+  "insertEndnote",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+    checkNonEmpty(args.text, "text");
+  }
 );
 var getFootnotes = forwardTool(
   "word_get_footnotes",
@@ -19705,7 +19789,11 @@ var insertBookmark = forwardTool(
     },
     required: ["name", "anchorText"]
   },
-  "insertBookmark"
+  "insertBookmark",
+  (args) => {
+    checkNonEmpty(args.name, "name");
+    checkNonEmpty(args.anchorText, "anchorText");
+  }
 );
 var deleteBookmark = forwardTool(
   "word_delete_bookmark",
@@ -19716,7 +19804,10 @@ var deleteBookmark = forwardTool(
     },
     required: ["name"]
   },
-  "deleteBookmark"
+  "deleteBookmark",
+  (args) => {
+    checkNonEmpty(args.name, "name");
+  }
 );
 var goToBookmark = forwardTool(
   "word_go_to_bookmark",
@@ -19727,7 +19818,10 @@ var goToBookmark = forwardTool(
     },
     required: ["name"]
   },
-  "goToBookmark"
+  "goToBookmark",
+  (args) => {
+    checkNonEmpty(args.name, "name");
+  }
 );
 var getBookmarkText = forwardTool(
   "word_get_bookmark_text",
@@ -19738,7 +19832,10 @@ var getBookmarkText = forwardTool(
     },
     required: ["name"]
   },
-  "getBookmarkText"
+  "getBookmarkText",
+  (args) => {
+    checkNonEmpty(args.name, "name");
+  }
 );
 var bookmarkTools = [
   getBookmarks,
@@ -19761,7 +19858,12 @@ var insertHyperlink = forwardTool(
     },
     required: ["anchorText", "url"]
   },
-  "insertHyperlink"
+  "insertHyperlink",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+    checkNonEmpty(args.url, "url");
+    checkUrl(args.url);
+  }
 );
 var getHyperlinks = forwardTool(
   "word_get_hyperlinks",
@@ -19780,7 +19882,10 @@ var removeHyperlink = forwardTool(
     },
     required: ["anchorText"]
   },
-  "removeHyperlink"
+  "removeHyperlink",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+  }
 );
 var hyperlinkTools = [
   insertHyperlink,
@@ -19809,7 +19914,10 @@ var insertContentControl = forwardTool(
       matchCase: { type: "boolean", description: "Default: false" }
     }
   },
-  "insertContentControl"
+  "insertContentControl",
+  (args) => {
+    checkNonEmpty(args.anchorText, "anchorText");
+  }
 );
 var setContentControlText = {
   name: "word_set_content_control_text",
@@ -20199,10 +20307,10 @@ var equationTools = [
 ];
 
 // src/server/tools/batch.ts
-function createBatchTool(registry, actionMap) {
+function createBatchTool(registry, actionMap, validators) {
   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: {
@@ -20268,6 +20376,16 @@ function createBatchTool(registry, actionMap) {
           break;
         }
         if (actionMap.has(op.tool)) {
+          const validate = validators.get(op.tool);
+          if (validate) {
+            try {
+              validate(op.args || {});
+            } catch (e) {
+              results.push({ index: i, tool: op.tool, success: false, error: e.message });
+              stopped = true;
+              break;
+            }
+          }
           nativeBuf.push({ tool: op.tool, args: op.args || {}, originalIndex: i });
         } else {
           const ok = await flushNative();
@@ -20327,13 +20445,17 @@ function buildToolRegistry() {
   ];
   const handlers = /* @__PURE__ */ new Map();
   const actionMap = /* @__PURE__ */ new Map();
+  const validators = /* @__PURE__ */ new Map();
   for (const tool of allTools) {
     handlers.set(tool.name, tool.handler);
     if ("bridgeAction" in tool && typeof tool.bridgeAction === "string") {
       actionMap.set(tool.name, tool.bridgeAction);
     }
+    if ("validate" in tool && typeof tool.validate === "function") {
+      validators.set(tool.name, tool.validate);
+    }
   }
-  const batchTool = createBatchTool(handlers, actionMap);
+  const batchTool = createBatchTool(handlers, actionMap, validators);
   allTools.push(batchTool);
   handlers.set(batchTool.name, batchTool.handler);
   return { tools: allTools, handlers };
@@ -20398,6 +20520,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.
@@ -20458,12 +20582,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.1",
+  version: "4.1.3",
   description: "MCP server for live Word document editing via Office Add-in",
   main: "dist/server.js",
   bin: {
@@ -20528,7 +20661,7 @@ function createMcpServer(bridge2) {
   );
   const { tools, handlers } = buildToolRegistry();
   const toolMutex = createMutex();
-  server.setRequestHandler(import_types8.ListToolsRequestSchema, async () => ({
+  server.setRequestHandler(import_types9.ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
@@ -20539,7 +20672,7 @@ function createMcpServer(bridge2) {
       }
     }))
   }));
-  server.setRequestHandler(import_types8.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);
@@ -20555,7 +20688,7 @@ function createMcpServer(bridge2) {
       }
     });
   });
-  server.setRequestHandler(import_types8.ListResourcesRequestSchema, async () => ({
+  server.setRequestHandler(import_types9.ListResourcesRequestSchema, async () => ({
     resources: [{
       uri: "word-bridge://usage-guide",
       name: "Word Bridge Usage Guide",
@@ -20563,7 +20696,7 @@ function createMcpServer(bridge2) {
       mimeType: "text/markdown"
     }]
   }));
-  server.setRequestHandler(import_types8.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 }] };
     }
@@ -20634,7 +20767,7 @@ function createHttpsServer() {
   };
   const rootDir = import_path.default.join(__dirname, "..");
   return import_https.default.createServer(options, (req, res) => {
-    let urlPath = (req.url || "/").split("?")[0];
+    const urlPath = (req.url || "/").split("?")[0];
     let filePath = urlPath === "/" ? "/taskpane.html" : urlPath;
     filePath = import_path.default.resolve(rootDir, "." + filePath);
     if (!filePath.startsWith(rootDir + import_path.default.sep) && filePath !== rootDir) {