mcp-word-bridge 4.0.3 → 4.0.5

package/README.md

@@ -1,5 +1,8 @@
 # MCP Word Bridge
 
+[![Tests](https://github.com/likelion/mcp-word-bridge/actions/workflows/tests.yml/badge.svg)](https://github.com/likelion/mcp-word-bridge/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/likelion/mcp-word-bridge/branch/main/graph/badge.svg)](https://codecov.io/gh/likelion/mcp-word-bridge)
+
 MCP server for live Word document editing via Office Add-in. Enables programmatic editing of Word documents through the Word JavaScript API, with changes appearing as user edits in co-authoring sessions.
 
 ## Quick Start
@@ -67,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 |

package/dist/server.js

@@ -18722,7 +18722,7 @@ var Bridge = class {
 
 // src/server/mcp.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
-var import_types5 = require("@modelcontextprotocol/sdk/types.js");
+var import_types7 = require("@modelcontextprotocol/sdk/types.js");
 
 // src/server/tools/helpers.ts
 function jsonResult(data) {
@@ -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,9 +18863,23 @@ 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.`);
+  }
+}
 function checkNonNegative(value, name) {
-  if (typeof value !== "number" || value < 0) {
-    throw new ToolError(`${name} must be non-negative.`);
+  if (typeof value !== "number" || value < 0 || !Number.isInteger(value)) {
+    throw new ToolError(`${name} must be a non-negative integer.`);
   }
 }
 function checkBounds(index, count, name) {
@@ -18898,6 +18901,22 @@ function checkOccurrence(occurrence, count) {
   }
   return idx;
 }
+var MAX_SPACING_POINTS = 1584;
+var MAX_CUSTOM_PROPERTY_KEY_LENGTH = 255;
+function checkSpacingBounds(value, name) {
+  if (value > MAX_SPACING_POINTS) {
+    throw new ToolError(
+      `${name} value ${value} exceeds maximum (${MAX_SPACING_POINTS} points = 22 inches). Use a value between 0 and ${MAX_SPACING_POINTS}.`
+    );
+  }
+}
+function checkPropertyKeyLength(key) {
+  if (key.length > MAX_CUSTOM_PROPERTY_KEY_LENGTH) {
+    throw new ToolError(
+      `key must be ${MAX_CUSTOM_PROPERTY_KEY_LENGTH} characters or fewer (got ${key.length}).`
+    );
+  }
+}
 
 // src/server/tools/paragraphs.ts
 var getParagraphs = forwardTool(
@@ -18987,10 +19006,10 @@ var setParagraphStyle = forwardTool(
   },
   "setParagraphStyle"
 );
-var setParagraphSpacing = forwardTool(
-  "word_set_paragraph_spacing",
-  "[Paragraphs] Set line spacing, before/after spacing, and indentation on a paragraph by index.",
-  {
+var setParagraphSpacing = {
+  name: "word_set_paragraph_spacing",
+  description: "[Paragraphs] Set line spacing, before/after spacing, and indentation on a paragraph by index.",
+  schema: {
     properties: {
       index: { type: "number", description: "Paragraph index (0-based)" },
       lineSpacing: { type: "number", description: "Line spacing in points" },
@@ -19002,8 +19021,26 @@ var setParagraphSpacing = forwardTool(
     },
     required: ["index"]
   },
-  "setParagraphSpacing"
-);
+  async handler(args, bridge2) {
+    const index = args.index;
+    checkNonNegative(index, "index");
+    const spacingFields = [
+      ["lineSpacing", args.lineSpacing],
+      ["spaceBefore", args.spaceBefore],
+      ["spaceAfter", args.spaceAfter],
+      ["firstLineIndent", args.firstLineIndent],
+      ["leftIndent", args.leftIndent],
+      ["rightIndent", args.rightIndent]
+    ];
+    for (const [name, value] of spacingFields) {
+      if (value !== void 0 && typeof value === "number") {
+        checkSpacingBounds(value, name);
+      }
+    }
+    const result = await bridge2.send("setParagraphSpacing", args);
+    return jsonResult(result);
+  }
+};
 var moveParagraph = {
   name: "word_move_paragraph",
   description: "[Paragraphs] Move paragraph(s) to another position. Preserves all rich content including footnotes, hyperlinks, formatting, images, and comments.",
@@ -19023,6 +19060,7 @@ var moveParagraph = {
     const location = args.location ?? "After";
     checkNonNegative(fromIndex, "fromIndex");
     checkNonNegative(toIndex, "toIndex");
+    if (!Number.isInteger(count)) throw new ToolError("count must be an integer.");
     if (count < 1) throw new ToolError("count must be at least 1");
     if (fromIndex === toIndex && count === 1) throw new ToolError("fromIndex and toIndex must be different");
     if (toIndex >= fromIndex && toIndex < fromIndex + count) {
@@ -19033,12 +19071,23 @@ var moveParagraph = {
     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 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) {
@@ -19071,14 +19120,22 @@ var copyParagraph = {
     const location = args.location ?? "After";
     checkNonNegative(fromIndex, "fromIndex");
     checkNonNegative(toIndex, "toIndex");
+    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;
     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 } });
   }
 };
@@ -19098,7 +19155,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" },
@@ -19109,10 +19166,10 @@ var search = forwardTool(
   },
   "search"
 );
-var searchAndReplace = forwardTool(
-  "word_search_and_replace",
-  "[Search] Find and replace ALL occurrences. For single-paragraph edits, prefer word_replace_paragraph_text.",
-  {
+var searchAndReplace = {
+  name: "word_search_and_replace",
+  description: "[Search] Find and replace ALL occurrences. For single-paragraph edits, prefer word_replace_paragraph_text.",
+  schema: {
     properties: {
       find: { type: "string" },
       replace: { type: "string" },
@@ -19121,8 +19178,18 @@ var searchAndReplace = forwardTool(
     },
     required: ["find", "replace"]
   },
-  "searchAndReplace"
-);
+  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.',
@@ -19496,7 +19563,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" },
@@ -19703,10 +19770,10 @@ var insertContentControl = forwardTool(
   },
   "insertContentControl"
 );
-var setContentControlText = forwardTool(
-  "word_set_content_control_text",
-  "[Content Controls] Set text in a content control identified by ID or tag. Does NOT work on CheckBox controls.",
-  {
+var setContentControlText = {
+  name: "word_set_content_control_text",
+  description: "[Content Controls] Set text in a content control identified by ID or tag. Does NOT work on CheckBox controls.",
+  schema: {
     properties: {
       id: { type: "number", description: "Content control ID" },
       tag: { type: "string", description: "Content control tag (alternative to ID)" },
@@ -19714,8 +19781,25 @@ var setContentControlText = forwardTool(
     },
     required: ["text"]
   },
-  "setContentControlText"
-);
+  async handler(args, bridge2) {
+    const tag = args.tag;
+    const id = args.id;
+    if (!tag && id === void 0) {
+      throw new ToolError('Provide "id" or "tag" to identify the content control. Use word_get_content_controls to list available controls.');
+    }
+    if (tag) {
+      const ccResult = await bridge2.send("getContentControls", {});
+      const matches = ccResult.controls.filter((c) => c.tag === tag);
+      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(", ")}.`
+        );
+      }
+    }
+    const result = await bridge2.send("setContentControlText", args);
+    return jsonResult(result);
+  }
+};
 var contentControlTools = [
   getContentControls,
   insertContentControl,
@@ -19930,18 +20014,24 @@ var getCustomProperties = forwardTool(
   { properties: {} },
   "getCustomProperties"
 );
-var setCustomProperty = forwardTool(
-  "word_set_custom_property",
-  "[Properties] Set a custom document property. Creates or updates the key-value pair.",
-  {
+var setCustomProperty = {
+  name: "word_set_custom_property",
+  description: "[Properties] Set a custom document property. Creates or updates the key-value pair.",
+  schema: {
     properties: {
       key: { type: "string" },
       value: { type: "string" }
     },
     required: ["key", "value"]
   },
-  "setCustomProperty"
-);
+  async handler(args, bridge2) {
+    const key = args.key;
+    checkNonEmpty(key, "key");
+    checkPropertyKeyLength(key);
+    const result = await bridge2.send("setCustomProperty", args);
+    return jsonResult(result);
+  }
+};
 var deleteCustomProperty = forwardTool(
   "word_delete_custom_property",
   "[Properties] Delete a custom document property by key.",
@@ -20310,7 +20400,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.3",
+  version: "4.0.5",
   description: "MCP server for live Word document editing via Office Add-in",
   main: "dist/server.js",
   bin: {
@@ -20328,7 +20418,14 @@ var package_default = {
     typecheck: "tsc --noEmit",
     prepublishOnly: "npm run build"
   },
-  keywords: ["mcp", "word", "office", "add-in", "document", "editing"],
+  keywords: [
+    "mcp",
+    "word",
+    "office",
+    "add-in",
+    "document",
+    "editing"
+  ],
   repository: {
     type: "git",
     url: "https://github.com/likelion/mcp-word-bridge.git"
@@ -20344,6 +20441,7 @@ var package_default = {
   devDependencies: {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.10",
+    "@vitest/coverage-v8": "^3.2.6",
     esbuild: "^0.25.0",
     eslint: "^10.4.1",
     typescript: "^5.7.0",
@@ -20366,7 +20464,7 @@ function createMcpServer(bridge2) {
     { capabilities: { tools: {}, resources: {} } }
   );
   const { tools, handlers } = buildToolRegistry();
-  server.setRequestHandler(import_types5.ListToolsRequestSchema, async () => ({
+  server.setRequestHandler(import_types7.ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
@@ -20377,7 +20475,7 @@ function createMcpServer(bridge2) {
       }
     }))
   }));
-  server.setRequestHandler(import_types5.CallToolRequestSchema, async (request) => {
+  server.setRequestHandler(import_types7.CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const handler = handlers.get(name);
     if (!handler) {
@@ -20391,7 +20489,7 @@ function createMcpServer(bridge2) {
       return { content: [{ type: "text", text: msg }], isError: true };
     }
   });
-  server.setRequestHandler(import_types5.ListResourcesRequestSchema, async () => ({
+  server.setRequestHandler(import_types7.ListResourcesRequestSchema, async () => ({
     resources: [{
       uri: "word-bridge://usage-guide",
       name: "Word Bridge Usage Guide",
@@ -20399,7 +20497,7 @@ function createMcpServer(bridge2) {
       mimeType: "text/markdown"
     }]
   }));
-  server.setRequestHandler(import_types5.ReadResourceRequestSchema, async (request) => {
+  server.setRequestHandler(import_types7.ReadResourceRequestSchema, async (request) => {
     if (request.params.uri === "word-bridge://usage-guide") {
       return { contents: [{ uri: request.params.uri, mimeType: "text/markdown", text: usageGuide }] };
     }